Title: Theory / Unimportant / CS / Descriptive / ReST / Sphinx
On every note of this deck, unless a note says otherwise:
Page: man
Prefix: sphinx-build sourcedir builddir

Name: sphinx
Definition: 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.
Page: https://www.sphinx-doc.org/en/master/usage/quickstart.html

Question: What does sphinx adds to reST
Answer: A way to connect multiple files to a single hierarchy of documents.
Page: https://www.sphinx-doc.org/en/master/usage/quickstart.htmla

Instruction: .. toctree::
  :maxdepth: n
  file_1
  ...
  file_f
Page: https://www.sphinx-doc.org/en/master/usage/quickstart.htmla
Language: rst
Returns: Include all documents file_i and create a table of content up to depth n of their content

Instruction: sphinx-build sourcedir builddir
Page: https://www.sphinx-doc.org/en/master/usage/quickstart.html
Effect: build the sphinx collection from sourcedir to builddir
Language: bash

Fla: -b foo
Effect: uses builder foo

Fla: -a
Effect: always write all output files

Fla: -E
Effect: Don't use a saved environment (the structure caching all cross-references), but rebuild it completely

Fla: -t tag
Effect: Define the tag tag
Intuition: This is relevant for only directives that only include their content if this tag is set.

Fla: -d path
Effect: put the doctree pickles at path

Fla: -j N
Effect: Distribute the build over N processes in parallel

Fla: -c path
Effect: uses the conf at path

Fla: -C
Effect: Don't look for a configuration file, only take options via -D

Fla: -D setting=value
Effect: Set setting to value, override the conf.py configuration

Fla: -A name=Value
Effect: Make the name assigned to value in the HTML templates.

Fla: -n
Effect: Run in nit-picky mode.  Currently, this generates warnings for all missing references.

Fla: -N
Effect: Do not emit colored output

Fla: -v
Effect: Increase verbosity

Fla: -q
Effect: Do not output anything on standard output, only write warnings and errors to standard error.

Fla: -Q
Effect: Do not output anything on standard output, also suppress warnings.  Only errors are written to standard error.

Fla: -w file
Effect: Write warnings (and errors) to the given file, in addition to standard error.

Fla: -W
Effect: Turn warnings into errors.

Fla: --keep-going
Effect: keep going to the end of file if possible, still output 1 to notice there was an error
Assuming: With -W option (warning into errors)

Fla: -T
Effect: Display the full traceback when an unhandled exception occurs.  Otherwise, only a summary is displayed and the traceback information is saved to a file for further analysis.

Fla: -P
Effect: Run the Python debugger, pdb, if an unhandled exception occurs while building.

Fla: --help
Flag abbreviation: -h
Print: Display usage summary

Fla: --version
Print: Display sphinx version

Name: A domain
Definition: The first part in a directive if it is of the form foo:bar::
Page: https://www.sphinx-doc.org/en/master/usage/quickstart.html
Example: 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.)
Intuition: a collection of object types that belong together, complete with markup to create and reference descriptions of these objects.

Instruction: sphinx-quickstart
Page: https://www.sphinx-doc.org/en/master/usage/quickstart.html
Effect: generate a file structure to begin a sphinx project
Language: bash

Name: Extension
Definition: a Python module that provides additional features for Sphinx projects
Page: https://www.sphinx-doc.org/en/master/usage/quickstart.html
Context: sphinx

Name: autodoc
Definition: An extension that allow to extract python documentation string
Page: https://www.sphinx-doc.org/en/master/usage/quickstart.html
Context: sphinx

Variable: extensions
Meaning: The list of extension used by this project
Page: https://www.sphinx-doc.org/en/master/usage/quickstart.html
Language: sphinx

Instruction: .. autofunction:: python_function
Page: https://www.sphinx-doc.org/en/master/usage/quickstart.html
Returns: the documentation of python_function
Name: sphinx

Instruction: .. autofunction:: module
  :members:
Page: https://www.sphinx-doc.org/en/master/usage/quickstart.html
Returns: the documentation of module
Name: sphinx

Instruction: make foo
Page: https://www.sphinx-doc.org/en/master/tutorial/first-steps.html
Effect: compile the documentation to the format foo
Name: sphinx

Name: The root document
Definition: A welcome page and to contain the root of the “table of contents tree” (or toctree)
Page: https://www.sphinx-doc.org/en/master/tutorial/narrative-documentation.html
Context: sphinx

Instruction: .. image:: name.*
Page: https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html
Language: sphinx
Returns: same as
... image:: name.FOO
where FOO is determined by the compiler to be the better available image format for the generated document

Instruction: .. meta::
  :prop_1: content_1
  ..
  :prop_n: content_n
Page: https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html
Language: sphinx
Returns: introduce in the generated html <meta name="prop_i" content = "content_i">

Instruction: :role:`title target`
Page: https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html
Language: sphinx
Returns: A link to target with text title according to :role:

Instruction: :role:`!target`
Page: https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html
Language: sphinx
Returns: Add a url but do not create an explicit link

Page: https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html
Syntactic sugar: :role:`~package_1...package_n.content`
Implementation: :role:`content ~package_1...package_n.content`
Language: sphinx

Instruction: :any:
Page: https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html
Language: sphinx
Returns: a role which will try to find it's link in any reference.

Instruction: :ref:`label`
Page: https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html
Language: sphinx
Returns: Add a link to label label. Title is determined from context of the label

Question: Advantage of :ref:`label` over `label`_
Answer: :ref:`label` works accross files in the same collection of document
Page: https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html
Context: sphinx

Question: Advantage of `label`_ over :ref:`label`
Answer: :ref:`label` requires uniqueness of name in the collection, while `label`_ only require it in the document
Page: https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html
Context: sphinx

Instruction: :doc:`file`
Page: https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html
Language: sphinx
Returns: A link to document file

Instruction: :download:`file`
Page: https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html
Language: sphinx
Returns: A link to document file that can be downloaded and not displayed by reST

Instruction: :numref:`fig`
Page: https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html
Language: sphinx
Returns: Add a link to figure fig, with content figure number

Instruction: :numref:`description fig`
Page: https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html
Language: sphinx
Returns: Add a link to figure fig, with content description, where %s and {name} are figure number and caption

Instruction: :envvar:`name`
Page: https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html
Language: sphinx
Returns: Introduce a link to the definition of an environment variable

Instruction: :token:`name`
Page: https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html
Language: sphinx
Returns: Introduce a link to the definition of a token name

Instruction: :keyword:`name`
Page: https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html
Language: sphinx
Returns: Introduce a link to the definition of a keyword name

Instruction: :option:`name`
Page: https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html
Language: sphinx
Returns: Introduce a link to the definition of an option name

Instruction: :term:`name`
Page: https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html
Language: sphinx
Returns: Introduce a link to the definition of a term name in a glossary

Instruction: :math:`eq`
Page: https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html
Language: sphinx
Returns: show eq as mathjax/latex math

Instruction: :eq:
Page: https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html
Language: sphinx
Returns: same as math:numref

Instruction: :abbr:`abbreviation (long)`
Page: https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html
Language: sphinx
Returns: Introduce an abbreviation to mean long

Instruction: :command:`name`
Page: https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html
Language: sphinx
Returns: Introduce an OS-level command name

Instruction: :dfn:`name`
Page: https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html
Language: sphinx
Returns: Mark the defining instance of a term in the text. (No index entries are generated.)

Instruction: :file:`name`
Page: https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html
Language: sphinx
Returns: show name as a filename

Instruction: :guilabel:and further directive
Page: https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html
Language: sphinx
Returns: todo

Instruction: source_suffix
Page: https://www.sphinx-doc.org/en/master/usage/markdown.html
Language: sphinx
Returns: map from file extension to tool to use