Sphinx per documentazione codice php

Question

Sphinx è una libreria Python per generare una buona documentazione da un set di file di testo formattati con la tecnologia ReST. Non lo strumento utilizzato per la ricerca full-text

Sono inoltre perfettamente a conoscenza degli strumenti doxygen/phpdoc. Sto cercando di capire se c'è un modo di usare Sphinx per documentare progetti di php? o anche qualsiasi altro linguaggio non Python?

http://sphinx.pocoo.org/

Answer 1

Sfinge e il riposo possono essere utilizzati come strumenti di documentazione generici, nella mia esperienza. Non c'è niente in Sphinx che ti obbliga a usarlo solo per progetti basati su Python. Ad esempio, nel mio lavoro, l'ho usato per creare una guida utente e un riferimento API XML-RPC. In entrambi i casi, non ho avuto alcun uso per sphinx.ext.autodoc o altri extra specifici di Python. La documentazione è stata scritta "a mano", con direttive ReST per lo più generiche, piuttosto che le direttive speciali fornite da Sphinx. Per quello che vale, non ho ancora avuto bisogno di creare una direttiva ReST personalizzata per la documentazione non Python.

Anche se stai lavorando con un progetto PHP, penso che troverai utile Sphinx. Ad esempio la maggior parte delle direttive fornite da the module specific markup sono in realtà abbastanza generali. Non vedo perché non potresti o non vorresti usare questi costrutti per documentare cose da lingue diverse da Python. Allo stesso modo, Sphinx rende abbastanza semplice il show code examples in other languages. C'è persino un valore di configurazione per cambiare l'impostazione predefinita in qualsiasi lingua supportata da Pygments (che include PHP). Se ti senti particolarmente ambizioso, potresti anche aggiungere create a Sphinx extension a qualcosa di rilevante dal tuo codice PHP.

Tutto ciò detto, assicuratevi di considerare il pubblico per il vostro progetto di documentazione. Mentre penso che Sphinx sia uno strumento eccellente e lo consiglierei per una vasta gamma di progetti di documentazione, se il tuo pubblico è in attesa di qualcos'altro, sii consapevole di ciò. Ad esempio, se si stava documentando un progetto Java, gran parte del pubblico potrebbe aspettarsi documenti in stile Javadoc. Se ti allontani da tale aspettativa, assicurati che non sia solo per i calci (vale a dire, ti dà documenti migliori di quelli che otterresti diversamente) ed essere pronto a (brevemente) a spiegare cosa hai fatto in modo diverso (ad es. FAQ risposta o introduzione).

Infine, qualsiasi documentazione è migliore di nessuna documentazione, indipendentemente dallo strumento utilizzato per crearli. Usa qualsiasi strumento che ti aiuti, se è la differenza tra ottenere qualcosa là fuori e no.

Answer 2

appena rilasciato pochi giorni fa: http://mark-story.com/posts/view/sphinx-phpdomain-released

Answer 3

Il progetto Doctrine, un ORM per PHP, utilizza Sfinge di generare la documentazione on-line su www.doctrine-project.org. Usano un pyice personalizzato per PHP. La documentazione è disponibile su Github allo https://github.com/doctrine/orm-documentation. Include il file PHP pyset personalizzato.

Anche il pacchetto python-pygments viene fornito con molti stili pygment che si possono provare cambiando il pygments_style = valore nella vostra sfinge conf.py file di configurazione. Ad esempio, per provare l'evidenziazione sytle pastie, che fa parte di python-pygments, si utilizza

pygments_sytle = 'pastie' 

Answer 4

CakePHP sta usando Sfinge per la sua nuova documentazione, e ho scritto la phpdomain per sfinge. Anche se non c'è un modo per includere automaticamente i blocchi di documenti php in sfinge, ritengo comunque che sia uno dei migliori strumenti di authoring della documentazione disponibili. È ottimo per una documentazione più narrativa.Ma con il phpdomain puoi anche creare documenti API.

Answer 5

Per quanto mi riguarda, è possibile documentare praticamente qualsiasi sintassi in Sphinx se non si limita alle lingue supportate da autodoc. È possibile creare riferimenti API belli utilizzando direttive Sphinx standard come .. class, .. method, .. function e altro. Funzionano perfettamente a parte il codice sorgente e non richiedono alcuna generazione e collegamento automatico alle fonti.

è anche possibile creare ammonimenti generici con un po 'di classe speciale, che si potrebbe poi agganciare ai CSS:

.. admonition Title 
    :class: Ololo 

    This text could be formatted any way you want, using the ``Ololo`` tag. 

ci sono anche ruoli (permettono classi personalizzate troppo) e altri mezzi di aggiunta di testo con un po' speciale formattazione, se le direttive originali non sono sufficienti per te.

Se si decide di creare i documenti asincroni dal codice sorgente, accertarsi di disabilitare la verifica della copertura del codice e di altre funzioni relative al codice nel proprio conf.py o nell'avvio del progetto.

PS: è possibile visualizzare una risposta molto buona sugli elementi con classi personalizzate here.

Answer 6

Come potete vedere ci sono un sacco di strumenti per aiutare voi con questo, in caso contrario, se si ha realmente bisogno, check it out:

https://blog.simpleigh.com/2012/08/php-documentation-and-sphinx