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

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