Furo Documentation Theme

Furo provides specific typographic styles designed for prose-heavy websites. When designing or customizing your site, consider the following elements provided by the theme:

• Font Families: Distinct font families are used for prose versus headings.
• Spacing: The theme includes predefined line spacing (leading) and paragraph spacing to ensure readability.
• Font Weight & Smoothing: The theme manages font weights and includes settings for antialiasing and font-smoothing.
• Heading Hierarchy: The theme supports a standard heading hierarchy (Heading 2 through Heading 6) with specific visual separation and interaction with main content blocks.

Furo defaults to light mode and automatically switches to dark mode based on the user's browser preference (prefers-color-scheme: dark).

Dark mode inherits variable definitions from light mode and only overrides specific values. While you cannot change the automatic switching mechanism, you can configure the specific CSS variables used for each mode.

To display different content (like images with specific backgrounds) depending on the mode, apply the only-dark or only-light CSS classes to your content.

Furo provides stability guarantees for users who use the theme out-of-the-box without custom templates or undocumented details. If you use standard features, you should not expect breaking changes. However, users implementing custom templates or overriding assets should be aware that these are considered 'unstable'.

Key points:

• Design tweaks: Minor design changes or new Sphinx support may be introduced in any release.
• Sphinx compatibility: New releases may drop support for older versions of Sphinx.
• Documented customizations: These are expected to remain stable unless explicitly marked as unstable.
• Undocumented/Unstable customizations: Furo makes no stability promises regarding exact filenames in theme templates or theme assets. If you override these, your configuration may break during updates.

Furo supports standard Sphinx markup, including both reStructuredText (reST) and Markdown (via MyST-Parser). It also supports several recommended third-party Sphinx extensions.

When writing documentation for Furo, you can use standard syntax for:

• Text formatting
• Admonitions
• API documentation
• Code blocks
• Hyperlinks
• Images
• Lists
• Tables
• Tabs

You can change the fonts across the entire page by overriding specific CSS variables within your Sphinx configuration. To ensure fonts are applied to both light and dark modes, set them under the light_css_variables key in html_theme_options.

Available variables:

• font-stack: Used for regular text.
• font-stack--monospace: Used for code blocks and inline code.
• font-stack--headings: Used for headings (added in version 2024.04.27).

html_theme_options = {
    "light_css_variables": {
        "font-stack": "Arial, sans-serif",
        "font-stack--monospace": "Courier, monospace",
        "font-stack--headings": "Georgia, serif",
    },
}

Use the .. image:: directive to embed images in your documentation. You can specify dimensions and alignment using options.

Available options:

• :height:: Set the image height.
• :width:: Set the image width.
• :target:: Make the image clickable by providing a URL.
• :align:: Align the image (e.g., left, right). Note that when using left or right alignment, you should provide enough surrounding text to prevent the 'floated' image from interfering with the document flow.

.. image:: https://picsum.photos/id/237/200/200
   :height: 200
   :width: 200

.. image:: https://picsum.photos/id/237/200/200
   :target: https://picsum.photos/
   :height: 200
   :width: 200

.. image:: https://picsum.photos/id/237/200/200
   :align: right
   :height: 200
   :width: 200

Furo supports standard reStructuredText inline markup for text styling and explicit roles for specific semantic meanings.

Text Styling:

• Bold: **text**
• Italics: *text*
• Inline code: `text`

Explicit Roles:

• Subscript: :sub:subscript`
• Superscript: :sup:superscript`
• Emphasis: :emphasis:emphasis`
• Strong: :strong:strong`
• Literal: :literal:literal`
• GUI Labels: :guilabel:label` (indicates user actions)
• Key-bindings: :kbd:KEY(e.g.,:kbd:⌘+⇧+M)
• Menu selections: :menuselection:Menu --> Submenu`
• Documented items (e.g., classes): :class:module.ClassName`

**bold**
*italics*
``inline code``
:sub:`subscript`
:sup:`superscript`
:guilabel:`Click Here`
:kbd:`Ctrl+C`
:menuselection:`File --> Open`
:class:`api_sample.RandomNumberGenerator`

List tables use a bulleted list format to define rows and columns, making them easier to maintain than grid tables. You can control column widths, specify header rows, and define stub columns using field options. They also support complex content like figures and long text within cells.

Supported options:

• :widths:: Defines the width of columns.
• :header-rows:: Specifies the number of header rows.
• :stub-columns:: Specifies the number of stub columns.

.. list-table:: List tables can have captions like this one.
    :widths: 10 5 10 50
    :header-rows: 1
    :stub-columns: 1

    * - List table
      - Header 1
      - Header 2
      - Header 3 long. Lorem ipsum dolor sit amet...
    * - Stub Row 1
      - Row 1
      - Column 2
      - Column 3 long. Lorem ipsum dolor sit amet...

To customize the title displayed in the sidebar of your Sphinx documentation, add the html_title variable to your conf.py file.

Setting html_title will overwrite the default sidebar title format, which is <project> <release> documentation. If you do not provide a release variable in conf.py, it will be omitted from the default title.

html_title = "your custom sidebar title"

Numbered lists can be used to create ordered sequences. The syntax is identical for both Markdown and reStructuredText: use a number followed by a period and a space.

1. Numbered lists are not complicated.
2. They do exactly what you think they do.