[bglug] Documentazione per progetti php

[Elena ``of Valhalla'']

On 2016-11-18 at 10:33:26 +0100, Steevie wrote:
> Più in dettaglio, io per diversi anni ho usato python-sphinx [1] per
> produrre documentazione (in particolare un manuale utente) sia in
> formato html che pdf (via Latex). Sphinx supporta molti altri formati
> (epub, man, info, singlehtml ecc), ma non li ho mai provati.

concordo col suggerimento su sphinx per produrre manuali: ha la
possibilità di aggiungere parti tecniche (come la documentazione
autogenerata delle api), ma non sono obbligatorie, lo si può usare
tranquillamente anche per manuali "semplici".

Un'alternativa è un generatore di siti statici, tipo pelican, che però
tende a dare un'impostazione più da sito con qualche pagina statica e un
blog che non da manuale.

> Molto simili come idea sono altri linguaggi di markup come asciidoc
> [2] o markdown [3] (solo output in html però), che sono sulla mia TODO
> list.

in realtà il linguaggio di markup usato è relativamente trasversale al
tool usato per la produzione dei documenti: molti strumenti oggi
supportano più formati per l'input e c'è pandoc_ che li supporta
all'incirca tutti e che permette di generare output all'incirca in tutti
i formati :)
Di suo è più indirizzato ad un modello un file di input - un file di
output, ma viene usato da altri strumenti che invece supportano bene la
"struttura" di documentazione varia per aggiungere supporto a formati
diversi.

.. _pandoc: http://pandoc.org/

Su che formato di markup leggero usare, io consiglio reStructuredText
(quello di sphinx), perché è stato progettato (anziché essere cresciuto
un po' per aggregazione) ed è nato esplicitamente pensando alla
scrittura di documentazione.

-- 
Elena ``of Valhalla''