additional_samples_with_very_long_name

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 second level heading (h2).

Sub-Heading

This is a third level heading (h3).

Sub-Sub-Heading

This is a fourth level heading (h4).

Code

The theme uses pygments for inline code text and

multiline
code text

Here’s an included example with line numbers.

  1"""MDAnalysis Sphinx theme."""
  2
  3import logging
  4import os
  5import pathlib
  6
  7import sass
  8from sass import SassColor, SassFunction
  9from sphinx.util import console
 10
 11logger = logging.getLogger(__name__)
 12
 13try:
 14    from .authors import __authors__
 15except ImportError:
 16    logger.info('Could not find authors.py, __authors__ will be empty.')
 17    __authors__ = []
 18
 19
 20from importlib.metadata import version
 21__version__ = version("mdanalysis_sphinx_theme")
 22
 23
 24def setup(app):
 25    """Setup connects events to the sitemap builder"""
 26    app.connect("build-finished", compile_css)
 27
 28    app.site_pages = []
 29    app.add_html_theme(
 30        "mdanalysis_sphinx_theme", html_theme_path()[0]
 31    )
 32    return {
 33        "version": __version__,
 34        "parallel_read_safe": True,
 35        "parallel_write_safe": True,
 36    }
 37
 38
 39def hex_to_rgb(hex):
 40    """Convert a hex color to RGB"""
 41    hex = hex.lstrip("#")
 42    return tuple(int(hex[i : i + 2], 16) for i in (0, 2, 4))
 43
 44
 45def compile_css(app, exception):
 46    """Compile Bulma SASS into CSS"""
 47    if exception is not None:
 48        return
 49
 50    theme_path = pathlib.Path(html_theme_path()[0])
 51    src = theme_path / "sass/site.sass"
 52    dest = pathlib.Path(app.outdir) / "_static/site.css"
 53
 54    if not dest.parent.exists():
 55        return
 56
 57    config = app.config["html_theme_options"]
 58    COLORS = {
 59        "mdanalysis-orange": (255, 146, 0),
 60        "mdanalysis-code-orange": (202, 101, 0),
 61        "white": (255, 255, 255),
 62        "dark-gray": (52, 49, 49),
 63    }
 64    theme_defaults = {
 65        "color_accent": "mdanalysis-code-orange",
 66        "sidebar_logo_background": "white",
 67        "mobile_navbar_background": "dark-gray",
 68    }
 69    function_colors = {}
 70    custom_sass_functions = {}
 71    for option, default in theme_defaults.items():
 72        theme_option = config.get(option, default)
 73        if theme_option in COLORS:
 74            color = COLORS[theme_option]
 75        else:
 76            color = hex_to_rgb(theme_option)
 77        function_colors[option] = color
 78
 79    if config.get("css_minify", False):
 80        output_style = "compressed"
 81        source_comments = False
 82    else:
 83        output_style = "expanded"
 84        source_comments = True
 85
 86    custom_sass_functions["mobile_navbar_background"] = lambda: SassColor(*function_colors["mobile_navbar_background"], 1)
 87    custom_sass_functions["sidebar_logo_background"] = lambda: SassColor(*function_colors["sidebar_logo_background"], 1)
 88    custom_sass_functions["color_accent"] = lambda: SassColor(*function_colors["color_accent"], 1)
 89    custom_sass_functions["hyphenate"] = lambda: config.get(
 90        "html_hyphenate_and_justify", False
 91    )
 92
 93    css = sass.compile(
 94        filename=str(src),
 95        output_style=output_style,
 96        custom_functions=custom_sass_functions,
 97    )
 98
 99    print(f"Writing compiled SASS to {console.colorize('blue', str(dest))}")
100
101    with open(dest, "w") as f:
102        print(css, file=f)
103
104
105def html_theme_path():
106    return [os.path.dirname(os.path.abspath(__file__))]
107

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";
}

Admonitions

The theme uses the admonition classes for the standard Sphinx admonitions.

Warning

Warning

This is a warning.

Attention

Attention

Do I have your attention?

Caution

Caution

Use caution!

Danger

Danger

This is danger-ous.

Error

Error

You have made a grave error.

Hint

Hint

Can you take a hint?

Important

Important

It is important to correctly use admonitions.

Note

Note

This is a note.

Tip

Tip

Please tip your waiter.

Deprecated

Deprecated since version 999.999.999: This API point was deprecated.

Todo

Todo

This is something we are yet to do.

Custom Admonitions

An admonition of my own making

You can create your own admonitions with the accent color.

Example

But lots of custom admonition styles are also defined.

Quote

The needs of the many outweigh the needs of the few

Bug

Bugs weren’t always a metaphor

Success

Woohoo!

Experimental

Experiments are the heart of science

Footnotes

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

Footnotes

Icons

Font Awesome and Academicons are both available:

<i class="fa fa-camera-retro fa-lg"></i>
<i class="fa fa-camera-retro fa-2x"></i>
<i class="fa fa-camera-retro fa-3x"></i>
<i class="fa fa-camera-retro fa-4x"></i>
<i class="fa fa-camera-retro fa-5x"></i>
<i class="ai ai-google-scholar-square ai-3x"></i>
<i class="ai ai-zenodo ai-3x" style="color: red"></i>

Tables

Here are some examples of Sphinx tables.

Grid

A grid table:

Header1

Header2

Header3

Header4

row1, cell1

cell2

cell3

cell4

row2 …

…

…

…

…

…

Simple

A simple table:

H1

H2

H3

cell1

cell2

cell3

…

…

…

…

…

…

List Tables

A List Table

Column 1

Column 2

Item 1

Item 2
50% width list table

One fifth width column

Four fifths width column

Item 1

Item 2

Alignment

Left Aligned

Column 1

Column 2

Item 1

Item 2
Center Aligned

Column 1

Column 2

Item 1

Item 2
Right Aligned

Treat

Quantity

Albatross

2.99

Crunchy Frog

1.49

Gannet Ripple

1.99

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