python-sphinx Handledning
Komma igång med python-sfinks
Sök…
Anmärkningar
Det här avsnittet ger en översikt över vad python-sfinks är och varför en utvecklare kanske vill använda den.
Det bör också nämna alla stora ämnen inom python-sfinksen och koppla till de relaterade ämnena. Eftersom dokumentationen för python-sfinx är ny kan du behöva skapa initialversioner av relaterade ämnen.
Installation eller installation
Eftersom Sphinx är tillgängligt på Python Package Index kan det installeras med pip :
pip install Sphinx
eller så kan du också installera med hjälp av easy_install
easy_install -U sphinx
Sedan kan du kontrollera att den har installerats korrekt genom att utföra följande kommando:
> sphinx-quickstart --version
Sphinx v1.4.1
Innan du går vidare måste du följa viss kodstil för python PEP 8 . Om du har följt PEP 8- riktlinjerna kan du definiera dokumentstruktur i sfinksen och börja bygga din dokumentation .
Snabbstart
För att komma igång går du till roten till projektkatalogen och kör:
$ sphinx-quickstart
Du får alternativ för att skapa dokumentation för ditt projekt. Följ nedanstående kommandon för standardinställningar:
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
Vid framgångsrik körning kan du upptäcka config.py-filen i din dokument- / källkatalog för ditt projekt. Den här filen har kontroll över grundstrukturen för hur ditt dokument kommer att genereras när du kör build-kommandot enligt nedan
$ sphinx-build -b html sourcedir builddir
Detaljerade instruktioner finns tillgängliga på: https://pythonhosted.org/an_example_pypi_project/sphinx.html