`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.

"""MDAnalysis Sphinx theme."""

import os
import pathlib

import sass
from sass import SassColor
from sphinx.util import console

from ._version import get_versions

__version__ = get_versions()["version"]
del get_versions


def setup(app):
    """Setup connects events to the sitemap builder"""
    app.connect("build-finished", compile_css)

    app.site_pages = []
    app.add_html_theme(
        "mdanalysis_sphinx_theme", html_theme_path()[0]
    )
    return {
        "version": __version__,
        "parallel_read_safe": True,
        "parallel_write_safe": True,
    }


def compile_css(app, exception):
    """Compile Bulma SASS into CSS"""
    if exception is not None:
        return

    theme_path = pathlib.Path(html_theme_path()[0])
    src = theme_path / "sass/site.sass"
    dest = pathlib.Path(app.outdir) / "_static/site.css"

    if not dest.parent.exists():
        return

    accent_color = app.config["html_theme_options"].get(
        "color_accent", "mdanalysis-orange"
    )
    accent_color = {
        "mdanalysis-orange": (255, 146, 0),
    }.get(accent_color, accent_color)

    if app.config["html_theme_options"].get("css_minify", False):
        output_style = "compressed"
        source_comments = False
    else:
        output_style = "expanded"
        source_comments = True

    css = sass.compile(
        filename=str(src),
        output_style=output_style,
        custom_functions={
            "accent_color": lambda: SassColor(*accent_color, 1),
            "hyphenate": lambda: app.config["html_theme_options"].get(
                "html_hyphenate_and_justify", False
            ),
        },
    )

    print(f"Writing compiled SASS to {console.colorize('blue', str(dest))}")

    with open(dest, "w") as f:
        print(css, file=f)


def html_theme_path():
    return [os.path.dirname(os.path.abspath(__file__))]

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

additional_samples_with_very_long_name