python-sphinx Tutorial
Iniziare con Python-Sfinge
Ricerca…
Osservazioni
Questa sezione fornisce una panoramica su cosa sia Python-sfinge e perché uno sviluppatore potrebbe volerlo usare.
Dovrebbe anche menzionare eventuali soggetti di grandi dimensioni all'interno di python-sfinge e collegarsi agli argomenti correlati. Poiché la Documentazione per python-sphinx è nuova, potrebbe essere necessario creare versioni iniziali di tali argomenti correlati.
Installazione o configurazione
Poiché Sphinx è disponibile sull'Indice dei Pacchetti Python , può essere installato usando pip :
pip install Sphinx
oppure puoi anche installare usando easy_install
easy_install -U sphinx
Quindi puoi verificare che sia stato installato correttamente eseguendo il seguente comando:
> sphinx-quickstart --version
Sphinx v1.4.1
Prima di procedere è necessario seguire lo stile di codice per Python PEP 8 . Se hai seguito la linea guida PEP 8 , puoi definire la struttura del documento nella sfinge e iniziare a costruire la tua documentazione .
Avvio veloce
Per iniziare vai alla directory principale del progetto ed esegui:
$ sphinx-quickstart
Otterrai le opzioni per creare documentazione per il tuo progetto. Per la configurazione di default segui i seguenti comandi:
Prompt Choice
> Root path for the documentation [.]: <ENTER>
> Separate source and build directories (y/N) [n]: y
> Name prefix for templates and static dir [_]: <ENTER>
> Project name: an_example_pypi_project
> Author name(s): Andrew Carter
> Project version: 0.0.1
> Project release [0.0.1]: <ENTER>
> Source file suffix [.rst]: <ENTER>
> Name of your master document (without suffix) [index]: <ENTER>
> autodoc: automatically insert docstrings from modules (y/N) [n]: y
> doctest: automatically test code snippets in doctest blocks (y/N) [n]: n
> intersphinx: link between Sphinx documentation of different projects (y/N) [n]: y
> todo: write “todo” entries that can be shown or hidden on build (y/N) [n]: n
> coverage: checks for documentation coverage (y/N) [n]: n
> pngmath: include math, rendered as PNG images (y/N) [n]: n
> jsmath: include math, rendered in the browser by JSMath (y/N) [n]: n
> ifconfig: conditional inclusion of content based on config values (y/N) [n]: y
> Create Makefile? (Y/n) [y]: n
> Create Windows command file? (Y/n) [y]: n
Al termine dell'esecuzione, è possibile scoprire il file config.py nella directory doc / source del progetto. Questo file ha il controllo sulla struttura di base del modo in cui il documento verrà generato quando si esegue il comando build come di seguito
$ sphinx-build -b html sourcedir builddir
Le istruzioni dettagliate sono disponibili all'indirizzo: https://pythonhosted.org/an_example_pypi_project/sphinx.html