python-sphinxAan de slag met python-sphinx


Opmerkingen

Deze sectie geeft een overzicht van wat python-sphinx is en waarom een ontwikkelaar het misschien wil gebruiken.

Het moet ook alle grote onderwerpen binnen python-sphinx vermelden en naar de gerelateerde onderwerpen verwijzen. Aangezien de documentatie voor python-sphinx nieuw is, moet u mogelijk eerste versies van die gerelateerde onderwerpen maken.

Installatie of instellingen

Aangezien Sphinx beschikbaar is op de Python-pakketindex , kan het worden geïnstalleerd met pip :

pip install Sphinx
 

of u kunt ook installeren met easy_install

easy_install -U sphinx
 

Vervolgens kunt u controleren of het correct is geïnstalleerd door de volgende opdracht uit te voeren:

> sphinx-quickstart --version
Sphinx v1.4.1
 

Voordat u doorgaat, moet u een bepaalde codestijl volgen voor python PEP 8 . Als u de PEP 8- richtlijn hebt gevolgd, kunt u de documentstructuur in sphinx definiëren en beginnen met het samenstellen van uw documentatie .

Snelle start

Ga om te beginnen naar de root van de projectmap en voer uit:

$ sphinx-quickstart
 

U krijgt opties om documentatie voor uw project te maken. Voor standaardinstellingen volg onderstaande opdrachten:

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
 

Na succesvolle uitvoering ontdekt u mogelijk het config.py-bestand in uw doc / source-directory van uw project. Dit bestand heeft controle over de basisstructuur van hoe uw document wordt gegenereerd wanneer u de build-opdracht uitvoert zoals hieronder

$ sphinx-build -b html sourcedir builddir

Gedetailleerde instructies zijn beschikbaar op: https://pythonhosted.org/an_example_pypi_project/sphinx.html