intro to sphinx

Defining_document_structure

  1. you did setup with sphinx-quickstart.

  2. conf.py, master document, index.rst generated as core

    • master document: serves welcome page, and contain root of the table of content tree TOCTree

  3. Toctree directive initially empty, and looks like,

TOCTREE_SAMPLE
.. toctree::
   :maxdepth: 2

   folder_at_conf/installation
   folder_at_conf/quickstart

이것은 정확히 sphinx에서 규정하는 toctree이다. 포함해야할 문서는 document names로써 주어진다. 요약하면, 파일 확장자는 신경끄고, 슬래쉬를 사용하여 dir-seperate만 해주면 된다. their section titles will be inserted(maxdepth레벨에 따라) at place where the toctree directive is placed. also, sphinx now know avout the order and hierarchy of your documents.

Adding_content

in sphinx source directory files, you can use most features of standard restructured_text. there are several features added by sphinx. for example, you cna add cross-file references in portable way using ref role.

if you are viewing the HTML version, you can look at the source for this coument use the “Show Source” link in the sidebar

Running_the_build

guess you added some files and content, A build is startd with sphinx-build program

sphinx-build -b html sourcedir builddir

sphinx-build-OPTIONS

  • -b buildername

    desc

    selects a builder

    Positional argument[buildername]
    • html

      default builder

    • dirhtml

      build html but sith single directory per-document, make for prettier URLS if served from a webserver

    • man

      manual pages in groff format for UNIX systems.

    • singlehtml

      single html with whole content

    • doctext

      run all doctests in documentation, if doctest extension is enabled

  • -M buildername

    desc

    Alternative to -b, Uses sphinx make_mode.

Documenting Objects

one of main objective of sphinx is documenting of objects in any domain.

domain

A Collection of object types that belong together, complete with markup to create and reference descriptions of there objects.

most prominent domain is Python domain, example in below…

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

Returns an Iterator that yields tuple of an index and it's value as a sequence
enumerate(sequence[, start=0])

Returns an Iterator that yields tuple of an index and it’s value as a sequence

there are more directives for documeting other types of python obj.

  • py:class

  • py:method

  • py:fuction

there is also cross-referencing role for each of there object types. this markup will create a link to documentation of ``enumerate()``

the enumerate() function can be used for …

if Python domain is the defaultone, py: can be ommited. and also doesn’t matter which file contains the actual doc for directive.

Each domain will have special rules for..

  • how the signatures can look like,

  • and make the fommated output look pretty

  • or add specific features like links to parameter types, e.g, c/c++ domains.

Basic configuration

since conf.py is executed by sphinx, you can do non-trival tasks in it, like extending sys.path or importing a module to find out the version you are documenting.

Autodoc

python conventially documents really a alot of docstrings. so, use extension called autodoc.

to activate it. in conf.py put the string sphinx.ext.autodoc into extensions config value.

extension = ['sphinx.ext.autodoc']

the, needs to add few additional directives at your disposal. for examlple, to document the fuction io.open(), reads its signature and docstring from the source file, like,

.. autofunction:: io.open

you can aslo document whole classes or even modules automatically, using member options for auto directives, like,

.. automodule:: io
   :members:

autodoc needs to import your modules in order to extract docstrings. therefore, you must add approrpicate path to sys.path in your conf.py

Warning

autodoc imports the modules to be documented.

Intersphinx

When you wnat to make links to such sphinx-documents on internet on your doc, you can do it with sphinx.ext.Intersphinx

to use them, activate it in conf.py by ‘sphinx.ext.intersphinx’ to extensions list and, set up the ``intersphinx_mapping config value.

for examlple, to lint to io.open() int the python lin intersphinx_mapping, setup your intersphinx_mapping like:

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

and now, you canr write cross-reference like io.open(). Any cross-ref that has no match will be looked up in documentation sets configured in intersphinx_mapping also works for some other domain’s rols including :ref:. not only python… but doesnt work for :doc: as that is non domain role.