[Docs] Infrastuttura per la gestione della documentazione

Manlio Perillo manlio_perillo a libero.it
Mer 23 Maggio 2007 13:05:46 CEST


Alan Franzoni ha scritto:
> Ho testato il py-rest-doc di Brandl. Il sistema non è malaccio ma è
> ancora un bel po' grezzo e ampiamente in fieri, e la toolchain
> necessita al momento di tutti i tool in versione sviluppo. Inoltre il
> webserver apposito non sembra partire in maniera corretta,
> lamentandosi della mancanza di un file che però la toolchain non ha
> generato.
> 
> Così, "a pelle", mi sembra davvero più carino usare reST piuttosto che
> LaTeX. Soprattutto sarebbe una buona idea, IMHO, usare lo stesso
> markup per le pagine del CMS che dovrebbe gestire il sito, e la
> documentazione. In questo modo si potrebbe dimezzare l'eventuale
> necessario tempo di apprendimento.
> 

Questo è un buon punto a favore.
Comunque non mi sembra il caso di approfondire il discorso, dato che il 
nuovo tool è solo una proposta.

Ne riparleremo quando la documentazione ufficiale verrà convertita nel 
nuovo formato.

Non dimentichiamo che avere la traduzione nello stesso formato del 
documento originale ha molti vantaggi.
Se riusciamo a completare la traduzione, possiamo anche chiedere alla 
PSF di includere la nostra traduzione sul loro sito.

Al momento il nostro problema non è i formati da usare, ma come 
organizzare i lavori.

> Mi pare che per il sito l'indecisione fosse proprio tra reST e
> Markdown... a meno che non troviamo anche un tool di conversione da/a
> Markdown, potrebbe essere proprio questo l'ago della bilancia.
> 

Parli di python.org o python.it?


Saluti  Manlio Perillo


Maggiori informazioni sulla lista Docs