`Additional` `Samples`¶

Various examples of styling applied to Sphinx constructs. You can view the source of this page to see the specific reStructuredText used to create these examples.

Headings¶

This is a first level heading (h1).

Sub-Heading¶

This is a second level heading (h2).

Sub-Sub-Heading¶

This is a third level heading (h3).

Code¶

The theme uses pygments for ``inline code text`` and
::

   multiline
   code text

The theme uses pygments for inline code text and

multiline
code text

Here’s an included example with line numbers.

.. literalinclude:: ../sphinx_immaterial/autodoc_property_type.py
   :caption: source from this theme in *sphinx_immaterial/autodoc_property_type.py*
   :linenos:

source from this theme in sphinx_immaterial/autodoc_property_type.py¶

"""Adds support for obtaining property types from docstring signatures, and
improves formatting by PyProperty of type annotations."""
import re
from typing import Tuple, Optional

import sphinx.addnodes
import sphinx.domains
import sphinx.domains.python
import sphinx.ext.autodoc

PropertyDocumenter = sphinx.ext.autodoc.PropertyDocumenter


property_sig_re = re.compile("^(\\(.*)\\)\\s*->\\s*(.*)$")


def _get_property_return_type(obj: property) -> Optional[str]:
    fget = getattr(obj, "fget", None)
    if fget is not None:
        obj = fget
    doc = obj.__doc__
    if doc is None:
        return None
    line = doc.splitlines()[0]
    line = line.rstrip("\\").strip()
    match = property_sig_re.match(line)
    if not match:
        return None
    _, retann = match.groups()
    return retann


def _apply_property_documenter_type_annotation_fix():

    # Modify PropertyDocumenter to support obtaining signature from docstring.

    orig_import_object = PropertyDocumenter.import_object

    def import_object(self: PropertyDocumenter, raiseerror: bool = False) -> bool:
        result = orig_import_object(self, raiseerror)
        if not result:
            return False
        if not self.retann:
            self.retann = _get_property_return_type(self.object)  # type: ignore
        return True

    PropertyDocumenter.import_object = import_object

    old_add_directive_header = PropertyDocumenter.add_directive_header

    def add_directive_header(self, sig: str) -> None:
        old_add_directive_header(self, sig)

        # Check for return annotation
        retann = self.retann or _get_property_return_type(self.object)
        if retann is not None:
            self.add_line("   :type: " + retann, self.get_sourcename())

    PropertyDocumenter.add_directive_header = add_directive_header

    # Modify PyProperty to improve formatting of :type: option
    PyProperty = sphinx.domains.python.PyProperty

    def handle_signature(
        self, sig: str, signode: sphinx.addnodes.desc_signature
    ) -> Tuple[str, str]:
        fullname, prefix = super(PyProperty, self).handle_signature(sig, signode)

        typ = self.options.get("type")
        if typ:
            signode += sphinx.addnodes.desc_sig_punctuation("", " : ")
            signode += sphinx.domains.python._parse_annotation(typ, self.env)

        return fullname, prefix

    PyProperty.handle_signature = handle_signature


_apply_property_documenter_type_annotation_fix()

It also works with existing Sphinx highlighting:

.. code-block:: html

   <html>
     <body>Hello World</body>
   </html>

.. code-block:: python

   def hello():
       """Greet."""
       return "Hello World"

.. code-block:: javascript

   /**
   * Greet.
   */
   function hello(): {
       return "Hello World";
   }

<html>
  <body>Hello World</body>
</html>

def hello():
    """Greet."""
    return "Hello World"

/**
* Greet.
*/
function hello(): {
    return "Hello World";
}

Footnotes¶

I have footnoted a first item [#f1]_ and second item [#f2]_.
This also references the second item [#f2]_.

.. rubric:: Footnotes
.. [#f1] My first footnote.
.. [#f2] My second footnote.

I have footnoted a first item 1 and second item 2. This also references the second item 2.

Footnotes

1: My first footnote.
2(1,2): My second footnote.

Icons¶

The following raw HTML¶

.. raw:: html

   <span style="font-size: 2rem;" class="md-icon">&#xe869;</span>

translates to the icon:



The material icon font provides hundreds to choose from. You can use the <i> tag or the <span> tag.

.. raw:: html

   <i style="font-size: 1rem;" class="md-icon">&#xe158;</i>
   <i style="font-size: 1.2rem;" class="md-icon">&#xe155;</i>
   <i style="font-size: 1.4rem;" class="md-icon">&#xe195;</i>
   <i style="font-size: 1.6rem;" class="md-icon">&#xe255;</i>
   <i style="font-size: 1.8rem;" class="md-icon">&#xe3c9;</i>
   <i style="font-size: 2.0rem;" class="md-icon">&#xe811;</i>
   <i style="font-size: 2.2rem;" class="md-icon">&#xe812;</i>
   <i style="font-size: 2.4rem;" class="md-icon">&#xe813;</i>
   <i style="font-size: 2.6rem;" class="md-icon">&#xe814;</i>
   <i style="font-size: 2.8rem;" class="md-icon">&#xe815;</i>

Tables¶

Here are some examples of Sphinx tables. The Sphinx Material all classes and only applies the default style to classless tables. If you want to use a custom table class, you will need to do two thing. First, apply it using .. cssclass:: custom-class and then add it to your configuration’s table_classes variable.

Grid¶

A grid table:¶

+------------------------+------------+----------+----------+
| Header1                | Header2    | Header3  | Header4  |
+========================+============+==========+==========+
| row1, cell1            | cell2      | cell3    | cell4    |
+------------------------+------------+----------+----------+
| row2 ...               | ...        | ...      |          |
+------------------------+------------+----------+----------+
| ...                    | ...        | ...      |          |
+------------------------+------------+----------+----------+

Header1	Header2	Header3	Header4
row1, cell1	cell2	cell3	cell4
row2 …	…	…
…	…	…

Simple¶

A simple table:¶

=====  =====  =======
H1     H2     H3
=====  =====  =======
cell1  cell2  cell3
...    ...    ...
...    ...    ...
=====  =====  =======

H1	H2	H3
cell1	cell2	cell3
…	…	…
…	…	…

User-styled Table¶

Note

table_classes is set to ["plain"] in the site’s configuration. Only plain remains as the class of the table. Other standard classes applied by Sphinx are removed.

This is feature demonstration. There is no css for the plain class, and so this is completely unstyled.

.. cssclass:: plain

=====  ======  =======
User   Styled  Table
=====  ======  =======
cell1  cell2   cell3
...    ...     ...
...    ...     ...
=====  ======  =======

User	Styled	Table
cell1	cell2	cell3
…	…	…
…	…	…

List Tables¶

.. list-table:: A List Table
   :header-rows: 1

   * - Column 1
     - Column 2
   * - Item 1
     - Item 2

A List Table¶
Column 1	Column 2
Item 1	Item 2

Alignment¶

.. list-table:: Center Aligned
   :header-rows: 1
   :align: center

   * - Column 1
     - Column 2
   * - Item 1
     - Item 2

Center Aligned¶
Column 1	Column 2
Item 1	Item 2

.. list-table:: Right Aligned
   :widths: 15 10 30
   :header-rows: 1
   :align: right

   * - Treat
     - Quantity
     - Description
   * - Albatross
     - 2.99
     - On a stick!
   * - Crunchy Frog
     - 1.49
     - If we took the bones out
   * - Gannet Ripple
     - 1.99
     - On a stick!

Right Aligned¶
Treat	Quantity	Description
Albatross	2.99	On a stick!
Crunchy Frog	1.49	If we took the bones out
Gannet Ripple	1.99	On a stick!

Code Documentation¶

An example Python function.¶

.. py:function:: format_exception(etype, value, tb[, limit=None])

   Format the exception with a traceback.

   :param etype: exception type
   :param value: exception value
   :param tb: traceback object
   :param limit: maximum number of stack frames to show
   :type limit: integer or None
   :rtype: list of strings

format_exception(etype, value, tb[, limit=None])¶

Format the exception with a traceback.

Parameters¶

etype¶: exception type
value¶: exception value
tb¶: traceback object
limit : integer or None: maximum number of stack frames to show

Return type¶

list of strings

An example JavaScript function.¶

.. js:class:: MyAnimal(name[, age])

   :param string name: The name of the animal
   :param number age: an optional age for the animal

class MyAnimal(name[, age])¶

Arguments¶

name (string()) – The name of the animal
age (number()) – an optional age for the animal

Glossaries¶

environment¶¶: A structure where information about all documents under the root is saved, and used for cross-referencing. The environment is pickled after the parsing stage, so that successive runs only need to read and parse new and changed documents.
source directory¶¶: The directory which, including its subdirectories, contains all source files for one Sphinx project.

Math¶

.. math::

   (a + b)^2 = a^2 + 2ab + b^2

   (a - b)^2 = a^2 - 2ab + b^2

\[ \begin{align}\begin{aligned}(a + b)^2 = a^2 + 2ab + b^2\\(a - b)^2 = a^2 - 2ab + b^2\end{aligned}\end{align} \]

.. math::

   (a + b)^2  &=  (a + b)(a + b) \\
              &=  a^2 + 2ab + b^2

\[\begin{split}(a + b)^2 &= (a + b)(a + b) \\ &= a^2 + 2ab + b^2\end{split}\]

.. math::
   :nowrap:

   \begin{eqnarray}
      y    & = & ax^2 + bx + c \\
      f(x) & = & x^2 + 2xy + y^2
   \end{eqnarray}

\begin{eqnarray} y & = & ax^2 + bx + c \\ f(x) & = & x^2 + 2xy + y^2 \end{eqnarray}

Production Lists¶

.. productionlist::
   try_stmt: try1_stmt | try2_stmt
   try1_stmt: "try" ":" `suite`
            : ("except" [`expression` ["," `target`]] ":" `suite`)+
            : ["else" ":" `suite`]
            : ["finally" ":" `suite`]
   try2_stmt: "try" ":" `suite`
            : "finally" ":" `suite`

try_stmt  ::=  try1_stmt | try2_stmt
try1_stmt ::=  "try" ":" suite
               ("except" [expression ["," target]] ":" suite)+
               ["else" ":" suite]
               ["finally" ":" suite]
try2_stmt ::=  "try" ":" suite
               "finally" ":" suite

Sub-pages¶

Last update: Jul 26, 2022

Additional Samples¶