sphynx templates

Теги: templating  python 

Sphynx - генератор документации для python проектов.

reStructuredText

  • one asterisk: *text* for emphasis (italics),
  • two asterisks: **text** for strong emphasis (boldface),
  • backquotes: ``text`` for code samples.

Lists and Quote-like blocks

* This is a bulleted list.
* It has two items, the second
  item uses two lines.

1. This is a numbered list.
2. It has two items too.

#. This is a numbered list.
#. It has two items too.

* this is
* a list

  * with a nested list
  * and some subitems

* and here the parent list continues

term (up to a line of text)
   Definition of the term, which must be indented

   and can even consist of multiple paragraphs

next term
   Description.

| These lines are
| broken exactly like in
| the source file.

Literal code blocks

This is a normal text paragraph. The next paragraph is a code sample::

   It is not processed in any way, except
   that the indentation is removed.

   It can span multiple lines.

This is a normal text paragraph again.

Doctest blocks

>>> 1 + 1
2

Tables

+------------------------+------------+----------+----------+
| Header row, column 1   | Header 2   | Header 3 | Header 4 |
| (header rows optional) |            |          |          |
+========================+============+==========+==========+
| body row 1, column 1   | column 2   | column 3 | column 4 |
+------------------------+------------+----------+----------+
| body row 2             | ...        | ...      |          |
+------------------------+------------+----------+----------+

or

=====  =====  =======
A      B      A and B
=====  =====  =======
False  False  False
True   False  False
False  True   False
True   True   True
=====  =====  =======

`Link text <https://domain.invalid/>`

or

This is a paragraph that contains `a link`_.

.. _a link: https://domain.invalid/

Sections

  • # with overline, for parts
  • * with overline, for chapters
  • = for sections
  • - for subsections
  • ^ for subsubsections
  • ” for paragraphs
=================
This is a heading
=================

Field Lists

Списки полей представляют собой последовательности полей, размеченных следующим образом: :fieldname: Field content

def my_function(my_arg, my_other_arg):
    """A function just for me.

    :param my_arg: The first of my arguments.
    :param my_other_arg: The second of my arguments.

    :returns: A message (just for me, of course).
    """

Подробнее

Roles

Роль или «пользовательская интерпретируемая текстовая роль» — это встроенный фрагмент явной разметки. Это означает, что вложенный текст следует интерпретировать определенным образом. Sphinx использует это для обеспечения семантической разметки и перекрестных ссылок идентификаторов. Общий синтаксис: :rolename:content. Поддерживаются, к примеру:

  • emphasis – equivalent of *emphasis*
  • strong – equivalent of **strong**
  • literal – equivalent of ``literal``
  • subscript – subscript text
  • superscript – superscript text
  • title-reference – for titles of books, periodicals, and other materials

Пример: Since Pythagoras, we know that :math:a^2 + b^2 = c^2.

Explicit Markup

«Явная разметка» используется в reST для большинства конструкций, требующих специальной обработки, таких как сноски, специально выделенные абзацы, комментарии и общие директивы.

Блок явной разметки начинается со строки, начинающейся с .., за которой следует пробел, и заканчивается следующим абзацем с тем же уровнем отступа. (Между явной разметкой и обычными абзацами должна быть пустая строка.

Dicrectives

Директива — это общий блок явной разметки. Наряду с ролями это один из механизмов расширения reST.

Подробнее тут

Others

Изображения, сноски, комментарии - смотри ниже

Подробнее обо всем этом тут: reStructuredText

Markdown

Configuration

Extentions

  • sphinx.ext.autodoc – Include documentation from docstrings
  • sphinx.ext.autosectionlabel – Allow reference sections using its title
  • sphinx.ext.autosummary – Generate autodoc summaries
  • sphinx-autogen – generate autodoc stub pages
  • sphinx.ext.coverage – Collect doc coverage stats
  • sphinx.ext.doctest – Test snippets in the documentation
  • sphinx.ext.duration – Measure durations of Sphinx processing
  • sphinx.ext.extlinks – Markup to shorten external links
  • sphinx.ext.githubpages – Publish HTML docs in GitHub Pages
  • sphinx.ext.graphviz – Add Graphviz graphs
  • sphinx.ext.ifconfig – Include content based on configuration
  • sphinx.ext.imgconverter – A reference image converter using Imagemagick
  • sphinx.ext.inheritance_diagram – Include inheritance diagrams
  • sphinx.ext.intersphinx – Link to other projects’ documentation
  • sphinx.ext.linkcode – Add external links to source code
  • sphinx.ext.imgmath – Render math as images
  • sphinx.ext.mathjax – Render math via JavaScript
  • sphinx.ext.jsmath – Render math via JavaScript
  • sphinx.ext.napoleon – Support for NumPy and Google style docstrings
  • sphinx.ext.todo – Support for todo items
  • sphinx.ext.viewcode – Add links to highlighted source code

[setuptools] integrations

link

Extending

Смотри еще: