Theme Installation

Theme Installation#

install packages#

Important

This is a setup guide for sphinx-book-theme, with several additional packages:

  • MyST

  • Sphinx Desing

  • Mermaid Diagramming

  • Sphinx Copybutton

The additional packages are necessary for this setup.


Install sphinx-book-theme with conda:

conda install#
    conda install -c conda-forge sphinx-book-theme

icon icon


Theme configuration at conf.py:

theme configuration#
        html_theme = "sphinx_book_theme"
        html_logo = "path/to/myimage.png" # (create folder, e.g. theme_custom)
        html_title = "My site title"
theme configuration#
        # -- adds source repository button on theme
        # -- current NOT Used

        html_theme_options = {
            ...
            "repository_url": "https://github.com/{your-docs-url}",
            "use_repository_button": True,
            ...
        }

See also

Package configuration details, see {book}theme.

MyST#

Markedly Structured Text - Parser


Install myst-parser with conda:

Note

to use markdown (files) for within this documenation

conda install#
        conda install -c conda-forge myst-parser

icon icon


Theme configuration at conf.py:

theme configuration#
        extensions = [
        ..
        'myst_parser',
        ..
        ]

        myst_enable_extensions = [
            'colon_fence',
            'attrs_block'
        ]

‘attrs_block’ enable parsing of block attributes before certain block syntaxes

See also

Package configuration details, see {MyST}theme.


Sphinx-Design#


Install sphinx-design with conda:

Note

A sphinx extension for designing beautiful, view size responsive web components.

conda install#
        conda install -c conda-forge sphinx-design

icon icon


Theme configuration at conf.py:

theme configuration#
        extensions = [
        ..
        'sphinx_design',
        ..
        ]

See also

Package configuration details, see {MyST}theme and Sphinx Design Documentation



Mermaid Diagramming#

Note

This extension allows you to embed Mermaid graphs in your documents, including general flowcharts, sequence diagrams, gantt diagrams and more.

Install sphinxcontrib-mermaid with conda:

conda install#
        conda install -c conda-forge sphinxcontrib-mermaid

icon icon


Theme configuration at conf.py:

theme configuration#
    extensions = [
    ..
    'sphinxcontrib.mermaid',
    ..
    ]

See also

Sphinx Mermaid Documentation



Sphinx Copybutton#

Install sphinx-copybutton with conda:

conda install#
        conda install -c conda-forge sphinx-copybutton

icon icon


Theme configuration at conf.py:

theme configuration#
    extensions = [
    ..
    'sphinx_copybutton',
    ..
    ]


config files#

The following files needs to be configured

conf.py#

‘conf.py’ should contain:

theme configuration#
    extensions = [
    ..
    'myst_parser',                      # TODO Check with DevTeam if deprecated, replaced
    'sphinx_design',
    'sphinxcontrib.mermaid',
    'sphinx_copybutton'
    ..
    ]

Warning

Order of extensions is relevant !

     extensions = [
    'myst_parser', 
    'sphinx_design',
    'sphinxcontrib.mermaid',
    'sphinx_copybutton'
    ]

‘requirements.txt’#

mandatory for readthedocs, also see your config at .readthedocs.yaml if it’s declared there

theme configuration#
# For readthedocs needed, otherwise import to readthedocs will fail
sphinx_book_theme
myst-parser
sphinx_design
sphinxcontrib.mermaid
sphinx_copybutton

# TODO Check with DevTeam if 'requirements.txt' is necessary, reommended or just for readthedocs setup

Contents