python-sphinx Samouczek
Rozpoczęcie pracy z python-sfinksem
Szukaj…
Uwagi
Ta sekcja zawiera przegląd tego, czym jest python-sfinks i dlaczego deweloper może chcieć go użyć.
Powinien również wymieniać wszelkie duże tematy w python-sphinx i link do powiązanych tematów. Ponieważ dokumentacja dla python-sfinksa jest nowa, może być konieczne utworzenie początkowych wersji tych pokrewnych tematów.
Instalacja lub konfiguracja
Ponieważ Sphinx jest dostępny w indeksie pakietów Pythona , można go zainstalować za pomocą pip :
pip install Sphinx
lub możesz także zainstalować za pomocą easy_install
easy_install -U sphinx
Następnie możesz sprawdzić, czy został poprawnie zainstalowany, wykonując następujące polecenie:
> sphinx-quickstart --version
Sphinx v1.4.1
Zanim przejdziesz dalej, musisz przestrzegać określonego stylu kodu dla Python PEP 8 . Jeśli postępujesz zgodnie z wytycznymi PEP 8 , możesz zdefiniować strukturę dokumentu w sfinksie i rozpocząć tworzenie dokumentacji .
Szybki start
Aby rozpocząć, przejdź do katalogu głównego katalogu projektu i uruchom:
$ sphinx-quickstart
Dostaniesz opcje tworzenia dokumentacji dla swojego projektu. Aby skonfigurować domyślnie, wykonaj następujące polecenia:
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
Po pomyślnym wykonaniu możesz odkryć plik config.py w katalogu doc / source swojego projektu. Ten plik ma kontrolę nad podstawową strukturą generowania dokumentu po uruchomieniu polecenia kompilacji, jak poniżej
$ sphinx-build -b html sourcedir builddir
Szczegółowe instrukcje są dostępne na stronie : https://pythonhosted.org/an_example_pypi_project/sphinx.html