`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

Here’s an included example with line numbers.

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

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


def _get_property_return_type(obj: property) -> Optional[str]:
    if obj.fget is None:
        return None
    doc = obj.fget.__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.
    PropertyDocumenter = sphinx.ext.autodoc.PropertyDocumenter

    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)
        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:

<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 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 template HTML:

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

translates to a the site’s icon:



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

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 …	…	…
…	…	…

Simple¶

A simple table:

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.

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

List Tables¶

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

Alignment¶

Warning

Alignment is not currently working as expected.

Center Aligned¶
Column 1	Column 2
Item 1	Item 2

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.

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.

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¶

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

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

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

Production Lists¶

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

Last update: Mar 15, 2022

Additional Samples¶