.. _sphinx_101: Sphinx 101 ========== ReST formatting --------------- For details on basic rST formatting, see the :ref:`sphinx:rst-primer` * *emphasis*, **strong empasis**, ``code`` * *``nesting``* ``*won’t*`` ````work```` * *roles* are formatted as ``:rolename:`some text```. See :ref:`roles` #. Numbered lists look like this 1. or like this, and can be nested, 2. as long as there is #. an empty line between the lists. * Definition lists have one line for the *term*, followed by one or more indented multiline paragraphs. Like this. * There must be a space between the link text and the url in `hyperlinks `_. * Conventions for header markup: #. ``#`` with overline #. ``*`` with overline #. ``=`` #. ``-`` #. ``^`` #. ``"`` .. _roles: Roles ----- All other roles are added by Sphinx Inline markup: reStructured text: :emphasis:`:emphasis:`, :strong:`:strong:`, :literal:`:literal:`, :subscript:`:subscript:`, :superscript:`:superscript:`, and :title-reference:`:title-reference:`. extra in Sphinx: :abbr:`:abbr:`, :command:`:command:`, :dfn:`:dfn:`, :file:`:file:`, :guilabel:`:guilabel:`, :kbd:`:kbd:`, :menuselection:`:menuselection:`, :mimetype:`:mimetype:`, :program:`:program:`, :regexp:`:regexp:`, :samp:`:samp:`. See :doc:`sphinx:usage/restructuredtext/roles`. Generic cross-referencing: Syntax: * ``:role:`target``` * ``:role:`title ``` displays ``title`` instead of the title provided by the reference. * ``:role:`!target``` doesn’t create a reference/hyperlink (bit still includes the title provided by the reference). * ``:role:`~path.to.target``` only displays the last segment of the target path. .. code-block:: rst :any: :ref: :doc: :envvar: :term: :pep: :rfc: Python cross-referencing: .. code-block:: rst :mod: :func: :data: :const: :class: :meth: :attr: :exc: :obj: Python info field lists: .. code-block:: rst :param str sender: The person sending the message :param priority: The priority of the message, can be a number 1-5 :type priority: integer or None :return: the message id :rtype: int or None :raises ValueError: if the message_body exceeds 160 characters :raises TypeError: if the message_body is not a basestring Container types can be linked automatically with the following syntax: .. code-block:: rst :type priorities: list(int) :type priorities: list[int] :type mapping: dict(str, int) :type mapping: dict[str, int] :type point: tuple(float, float) :type point: tuple[float, float] Multiple types in a type field will be linked automatically if separated by the word :dfn:`or`. Directives ---------- Explicit Markup Block begins with a line starting with ``..`` followed by whitespace and is terminated by the next paragraph at the same level of indentation. Directives are Explicit Markup with special semantics. Directives and roles form the extension mechanism of rST. Basically, a directive consists of a **name**, **arguments**, **options** and **content**: .. code-block:: rst .. name:: arg1 arg2 :option1: arg, arg :option2: Content Directives are defined by * :ref:`Docutils `; * :doc:`Sphinx domains ` such as the :ref:`Python domain `; * Sphinx Extensions. See :doc:`sphinx:usage/restructuredtext/directives` for documentation of many handy directives, such as: .. code-block:: rst .. note:: .. warning:: .. versionadded:: version .. versionchanged:: version .. deprecated:: version .. seealso:: .. hlist:: Google-style docstrings ----------------------- Example:: Args: path (str): The path of the file to wrap field_storage (FileStorage): The :class:`FileStorage` instance to wrap temporary (bool): Whether or not to delete the file when the File instance is destructed Returns: BufferedFileStorage: A buffered writable file descriptor The following section headers are supported: * **Args** (alias of **Parameters**) * **Arguments** (alias of **Parameters**) * **Attributes** * **Example** * **Examples** * **Keyword Args** (alias of **Keyword Arguments**) * **Keyword Arguments** * **Methods** * **Note** * **Notes** * **Other Parameters** * **Parameters** * **Return** (alias of **Returns**) * **Returns** * **Raises** * **References** * **See Also** * **Todo** (doesn't work together with `sphinx.ext.todo `_: items won't show up in the ``.. todolist::``) * **Warning** * **Warnings** (alias of **Warning**) * **Warns** * **Yield** (alias of **Yields**) * **Yields** Autodoc ------- See :doc:`sphinx:usage/extensions/autodoc`. .. code-block:: rst .. automodule:: my_module :members: :members: member1, member2 :undoc-members: :private-members: :special-members: :synopsis: Short description :platform: Linux, OS-X, other platform :deprecated: :show-inheritance: :inherited-members: .. autoclass:: MyClass .. autoexception:: MyException :members: :members: member1, member2 :undoc-members: :private-members: :special-members: :show-inheritance: :inherited-members: .. autofunction:: my_function .. autofunction:: my_function(arg1, arg2) .. automethod:: my_method .. automethod:: my_method(arg1, arg2) .. autodata:: .. autoattribute:: :annotation: Short description Three ways of documenting *module data members* and *class attributes*:: #: Single- or multi-line comment before the definition, #: starting with ``#:``. foo = "bar" #: Single line comment *after* the definition. """Docstring below the definition.""" Intersphinx ----------- Intersphinx is configured with the following mappings:: intersphinx_mapping = { 'python': ('https://docs.python.org/3.6/', 'python.inv'), 'sphinx': ('http://www.sphinx-doc.org/en/stable/', 'sphinx.inv'), 'aiohttp': ('http://aiohttp.readthedocs.io/en/stable/', 'aiohttp.inv'), 'aiopg': ('https://aiopg.readthedocs.io/en/stable/', 'aiopg.inv'), 'jwt': ('https://pyjwt.readthedocs.io/en/latest/', 'jwt.inv'), } For each of these external packages, a full list of available reference targets can be found in the corresponding :file:`*.inv.txt` files in the :file:`sphinx/` directory (after the first build).