Pierwsze kroki

Sphinx is a documentation generator or a tool that translates a set of plain text source files into various output formats, automatically producing cross-references, indices, etc. That is, if you have a directory containing a bunch of reStructuredText or Markdown documents, Sphinx can generate a series of HTML files, a PDF file (via LaTeX), man pages and much more.

Sphinx focuses on documentation, in particular handwritten documentation, however, Sphinx can also be used to generate blogs, homepages and even books. Much of Sphinx’s power comes from the richness of its default plain-text markup format, reStructuredText, along with its significant extensibility capabilities.

The goal of this document is to give you a quick taste of what Sphinx is and how you might use it. When you’re done here, you can check out the installation guide followed by the intro to the default markup format used by Sphinx, reStructuredText.

For a great „introduction” to writing docs in general – the whys and hows, see also Write the docs, written by Eric Holscher.

Ustawienie źródeł dokumentacji

The root directory of a Sphinx collection of plain-text document sources is called the source directory. This directory also contains the Sphinx configuration file conf.py, where you can configure all aspects of how Sphinx reads your sources and builds your documentation. [1]

Sphinx comes with a script called sphinx-quickstart that sets up a source directory and creates a default conf.py with the most useful configuration values from a few questions it asks you. To use this, run:

$ sphinx-quickstart

Określanie struktury dokumentu

Let’s assume you’ve run sphinx-quickstart. It created a source directory with conf.py and a root document, index.rst. The main function of the root document is to serve as a welcome page, and to contain the root of the „table of contents tree” (or toctree). This is one of the main things that Sphinx adds to reStructuredText, a way to connect multiple files to a single hierarchy of documents.

reStructuredText directives

toctree jest dyrektywą <directive> reStructuredTextu, bardzo uniwersalnym kawałkiem składni. Dyrektywy mogą mieć argumenty, opcje i treść.

Argumenty są podawane bezpośrednio po podwójnym dwukropku następującym po nazwie dyrektywy. Każda dyrektywa decyduje czy może mieć argumenty i ile.

Opcje są podawane za argumentami, w formie „listy pól”. maxdepth jest taką opcją dla dyrektywy toctree.

Treść oddzielna jest od opcji lub argumentów pustą linią. Każda dyrektywa decyduje czy dopuszczać treść i co z nią zrobić.

Częstym haczykiem w dyrektywach jest to, że pierwsza linia treści musi być wcięta na tym samym poziomie co opcje.

The toctree directive initially is empty, and looks like so:

.. toctree::
   :maxdepth: 2

You add documents listing them in the content of the directive:

.. toctree::
   :maxdepth: 2

   usage/installation
   usage/quickstart
   ...

This is exactly how the toctree for this documentation looks. The documents to include are given as document names, which in short means that you leave off the file name extension and use forward slashes (/) as directory separators.

Zobacz także

Read more about the toctree directive.

You can now create the files you listed in the toctree and add content, and their section titles will be inserted (up to the maxdepth level) at the place where the toctree directive is placed. Also, Sphinx now knows about the order and hierarchy of your documents. (They may contain toctree directives themselves, which means you can create deeply nested hierarchies if necessary.)

Dodawanie treści

In Sphinx source files, you can use most features of standard reStructuredText. There are also several features added by Sphinx. For example, you can add cross-file references in a portable way (which works for all output types) using the ref role.

For an example, if you are viewing the HTML version, you can look at the source for this document – use the „Show Source” link in the sidebar.

Zobacz także

reStructuredText for a more in-depth introduction to reStructuredText, including markup added by Sphinx.

Uruchamianie buildu

Now that you have added some files and content, let’s make a first build of the docs. A build is started with the sphinx-build program:

$ sphinx-build -M html sourcedir outputdir

where sourcedir is the source directory, and outputdir is the directory in which you want to place the built documentation. The -M option selects a builder; in this example Sphinx will build HTML files.

Zobacz także

Refer to the sphinx-build man page for all options that sphinx-build supports.

You can also build a live version of the documentation that you can preview in the browser. It will detect changes and reload the page any time you make edits. To do so, use sphinx-autobuild to run the following command:

$ sphinx-autobuild source-dir output-dir

However, sphinx-quickstart script creates a Makefile and a make.bat which make life even easier for you. These can be executed by running make with the name of the builder. For example.

$ make html

This will build HTML docs in the build directory you chose. Execute make without an argument to see which targets are available.

Jak generować dokumenty PDF?

make latexpdf uruchamia builder LaTeX-a i łatwo wywołuje dla ciebie toolchain pdfTeX.

Dokumentowanie obiektów

Jednym z głównych celów Sphinksa jest łatwa dokumentacja obiektów <objects> (w bardzo ogólnym znaczeniu) w dowolnej domenie <domain>. Domena jest kolekcją typów obiektów, które stanowią całość, razem ze znacznikami do tworzenia i odwoływania się do opisów tych obiektów.

The most prominent domain is the Python domain. For example, to document Python’s built-in function enumerate(), you would add this to one of your source files.

.. py:function:: enumerate(sequence[, start=0])

   Return an iterator that yields tuples of an index and an item of the
   *sequence*. (And so on.)

Wyrenderuje się to w ten sposób:

enumerate(sequence[, start=0])

Zwraca iterator, który daje krotki z indeksu i elementu sequence. (I tak dalej.)

Argumentem dyrektywy jest sygnatura <signature> obiektu, który opisujesz, treścią jest jego dokumentacja. Można podać wiele sygnatur, każdą w swojej linii.

The Python domain also happens to be the default domain, so you don’t need to prefix the markup with the domain name.

.. function:: enumerate(sequence[, start=0])

   ...

robi to samo, jeśli zachowasz domyśle ustawienie dla domyślnej domeny.

There are several more directives for documenting other types of Python objects, for example py:class or py:method. There is also a cross-referencing role for each of these object types. This markup will create a link to the documentation of enumerate().

The :py:func:`enumerate` function can be used for ...

A tutaj jest dowód: A link to enumerate().

Znów można pominąć py:, jeśli domena Pythona jest domyślną domeną. Nie ma znaczenia, który plik zawiera dokumentację dla enumerate(); Sphinx znajdzie ją i stworzy do niej link.

Każda domena będzie miała specjalne zasady jak mogą wyglądać sygnatury i spowoduje, że sformatowane wyjście będzie dobrze wyglądało, lub doda specyficzne funkcje takie jak linki do typów parametrów, na przykład w domenach C/C++.

Zobacz także

Domains for all the available domains and their directives/roles.

Podstawowa konfiguracja

Wspomnieliśmy wcześniej, że plik conf.py kontroluje sposób, w jaki Sphinx przetwarza twoje dokumenty. W tym pliku, który jest wykonywany jako plik źródłowy Pythona, możesz przypisać wartości konfiguracyjne. Dla zaawansowanych użytkowników: jako że jest wykonywany przez Sphinksa, możesz robić w nim nietrywialne zadania, takie jak rozszerzanie sys.path lub importowanie modułu, aby sprawdzić wersję, którą dokumentujesz.

The config values that you probably want to change are already put into the conf.py by sphinx-quickstart and initially commented out (with standard Python syntax: a # comments the rest of the line). To change the default value, remove the hash sign and modify the value. To customize a config value that is not automatically added by sphinx-quickstart, just add an additional assignment.

Keep in mind that the file uses Python syntax for strings, numbers, lists and so on. The file is saved in UTF-8 by default, as indicated by the encoding declaration in the first line.

Zobacz także

Configuration for documentation of all available config values.

Autodoc

When documenting Python code, it is common to put a lot of documentation in the source files, in documentation strings. Sphinx supports the inclusion of docstrings from your modules with an extension (an extension is a Python module that provides additional features for Sphinx projects) called autodoc.

Zobacz także

sphinx.ext.autodoc for the complete description of the features of autodoc.

Intersphinx

Many Sphinx documents including the Python documentation are published on the Internet. When you want to make links to such documents from your documentation, you can do it with sphinx.ext.intersphinx.

In order to use intersphinx, you need to activate it in conf.py by putting the string 'sphinx.ext.intersphinx' into the extensions list and set up the intersphinx_mapping config value.

For example, to link to io.open() in the Python library manual, you need to setup your intersphinx_mapping like:

intersphinx_mapping = {'python': ('https://docs.python.org/3', None)}

And now, you can write a cross-reference like :py:func:`io.open`. Any cross-reference that has no matching target in the current documentation set, will be looked up in the documentation sets configured in intersphinx_mapping (this needs access to the URL in order to download the list of valid targets). Intersphinx also works for some other domain's roles including :ref:, however it doesn’t work for :doc: as that is non-domain role.

Zobacz także

sphinx.ext.intersphinx for the complete description of the features of intersphinx.

More topics to be covered

Footnotes