Documentation¶

This is the documentation of Sphinx theme Simrofy.

Note

This documentation is mainly for the Simrofy theme, not the Sphinx itself. If you are new to Sphinx, please visit the Sphinx main website Sphinx for details. In additional, the Examples chapter of this website also provides a lot of useful information.

reStructuredText (reST) is not mandantory but highly recommended. Although you can write Markdown with recommonmark extension, many features of Sphinx is only avaliable to reStructuredText syntax. To learn its syntax, you can view a quick guide on Docutils, or visit the reST guidance page on Sphinx.

Caution

Simrofy is still in beta and its features and options may change very often.

Last updated was on 2022-06-16.

Overview¶

The Simrofy theme provides following features (for a full theme options list, see Theme Options section below):

Headbar: It can't be hidden. Users can decide what link to display (headbar_links), adjust its height (headbar_height).
- The "Raw" button can be disabled in conf.py (see Quick Guide section).
- The Github button is disabled by default, unless user use options github_user and github_repo.
- The language switching menu on the left of the headbar is supported by the i18n feature of Sphinx. See languages for details.
Sidebar: Users can enable/disable it, adjust its width and position. See options sidebar_position and sidebar_width.
- Sidebar generates a toctree with maxdepth 2 (i.e. only including <h1> and <h2> headings).
- The logo image is enabled by logo and its width can be adjusted by logo_width. You can use a circle-cropped style logo by given logo_radius.
- The background color of sidebar is given by sidebar_color.
Page components:
- Bibliography: Print a bibliography by parsing a *.bib file. See Bibliography section for details.
- Team photos: Show photos of team members with their contact information using people and people_pages.
Others
- Customize admonition colors by options like admonition_**_color.
- Add social media icons and weblinks by social_accounts.

Other customization can be achieved through adding/editing template, CSS or JavaScript files. Please view the source code of Simrofy and/or Sphinx' templating guide.

Installation¶

Simrofy relies on few Dependencies and is easily to fetch using pip, the command line package manager that goes with Python.

Dependencies¶

Simrofy is a Sphinx theme, so I assume that you don't need it if you haven't installed Sphinx.

Dependencies:

Python (>=3.6 recommended)

Version >= 3.6 is rcommended because f-string syntax is added in this version and I used that a lot. Lower version may be OK but I didn't test.

Visit Python Official Website to install Python.
Sphinx (>= 4.0.0)

Always better to choose a newer Sphinx version. You can scroll down to read the footer of current webpage and find under which Sphinx version this document was built; all versions no earlier than it should be good.

After installing Python, you can follow the download instruction of Sphinx to install it via pip command.

Optional dependencies:

nbsphinx

This extension lets users include Jupyter Notebook (.ipynb) files. The output style of the notebook is highly inherited in the HTML builds, which is an easy and clear way to present code-and-text documents.
sphinxcontrib-bibtex

This extension is for users who would like to print bibliography list and use citations on their website. It allows loading BibTeX file (*.bib) for external. Users can also customize filters, sorting and citation style with its advanced features. See its offical guide at sphinxcontrib-bibtex, or read Bibliography section of Simrofy documentation.
sphinx-intl

This extension is for internationalization. If you don't translate your website into multiple languages, you won't use this package.

Installation via Pip¶

Important

The early version of Simrofy won't be avaliable on Pypi (but on TestPypi instead) since I think it is not good enough to be post there. However, if you still want to install it and play around, you can get it via TestPypi:

# For developers only!
pip install --index-url https://test.pypi.org/simple/ -U sphinx-simrofy-theme

This is the recommended way to install Simrofy theme. Open your command line terminal and run following command:

pip install -U sphinx-simrofy-theme

The arg -U ensures upgrading to the newest version.

Building Simrofy by yourself¶

Tip

Skip this section if you've successfully installed Simrofy through pip command.

If you can't install it via pip, an alternative is to consider downloading the source code of Simrofy and compile it by yourself.

Download the source code of Simrofy from the Github repository. You can click on the Github link on the webpage sidebar.
Enter the folder and focus on following files:
```
dist/
sphinx_simrofy_theme/
    static/
    ...
setup.py
...
```
Then launch your command line terminal with current folder as the working directory.
In your terminal, run:
```
python setup.py sdist bdist_wheel
```
If you encounter an error, probably because you haven't installed the wheel package. Install it and try above building again:
```
pip install wheel
```
You will find compiled packages under the dist/ folder. Then you can directly install it by pip:
```
pip install dist/sphinx_simrofy_theme-VERSION.EXTENSION
```
Replace VERSION with version string of your build (like 1.0.0 ) and EXTENSION with package extension (either whl or tar.gz ). For example, "sphinx_simrofy_theme-0.4.1.whl" is a common choice for Windows users who are installing version 0.4.1.
You have finished building Simrofy and it has been installed on your machine.

Quick Guide¶

To apply Simrofy theme to your Sphinx project, put following line inside your conf.py:

html_theme = 'sphinx-simrofy-theme'  # These symbols are hyphens, not underlines!

Then you can follow the general Sphinx writing process. To customize Simrofy theme, use html_theme_options variable in the conf.py file. See Theme Options section below.

Embedding Videos¶

Embedding video is a little tricky in this theme. For most video websites, they allow users to create an embedded video using the share button. The HTML code usually includes an <iframe> element.

To include such a <iframe>, user may type:

.. raw:: html

   <div class="embedded-video">
     <iframe src="https://player.bilibili.com/player.html?aid=711068977&bvid=BV1TD4y1Q78b&cid=203195051&page=1&danmaku=0" scrolling="no" border="0" frameborder="no" framespacing="0" allowfullscreen="true"></iframe>
   </div>

Note the <div class="embedded-video"> in the first line. Don't forget to embedding the 'iframe' element inside such a DIV container. Its CSS style is predefined to have a maximum of 90% width and always keep a 16:9 ratio.
For Bilibili video links, please:
- Change the // heading into https://.
- Disable danmaku: Add &danmaku=0 to the SRC attribute of the <iframe> element.

Above embedded video gives:

Other notes¶

The 'Raw' button on the headbar can be removed by disabling copy source files into _sources path of the output folder. Use html_copy_source = False in conf.py to disable it.
The mechanism behind the default headbar links (or user-defined headbar_links ) is pretty unclear since Sphinx doesn't provide a simple way to read the doctree list. User needs to avoid using any of following substrings in document filenames:
- href= , or
- double semicolons ;;.
These strings are used for processing the output of toctree call of the Sphinx builder. Embedding them in filenames may cause building error or unexpected HTTML outputs.

Theme Options¶

In the conf.py file, we can specify theme options through the html_theme_options dictionary variable. For example:

html_theme_options = {
    'sidebar_position': 'left',
    'sidebar_width': 300,
    ...
}

Default values of theme options¶

All dictionary keys used in html_theme_options should be designed in the Simrofy theme. Please check the theme.conf file's [options] sections for details. For convinience, I also put the whole file here:

[theme]
inherit = basic
stylesheet = simrofy.css
pygments_style = default

[options]
canonical_prefix = 
favicon = 
logo =
logo_width = 0.8
logo_radius = 

github_user =
github_repo =
social_accounts = 

headbar_color = royalblue
headbar_height = 30
headbar_links = 
languages = 

image_self = 
people = 
people_pages = 
photo_subpath = 

sidebar_color = #23A97F
sidebar_home_text = 
sidebar_localtoc = 
sidebar_toc_exclude = 
sidebar_position = left
sidebar_width = 240
toc_depth = 2

admonition_attention_color = lightsalmon
admonition_caution_color = lightsalmon
admonition_danger_color = lightpink
admonition_error_color = lightpink
admonition_hint_color = lightgreen
admonition_important_color = lightgreen
admonition_note_color = lightskyblue
admonition_tip_color = lightgreen
admonition_warning_color = lightsalmon

Full references of theme options¶

Here is a parameter list for Simrofy's theme options. You may refer to the appendix conf.py file section to see how these options are used in this website.

admonition_**_color¶

Passing a CSS color strings to override the default admonition background color, where ** is the admonition name (attention, caution, etc.).

For example, user can change the color of these admonitions by passing values to the html_theme_options dictionary:

html_theme_options = {
    ...
    "admonition_attention_color": "red",
    "admonition_note_color": "#C8EBFA",
    ...
}

Default admonition colors are similar to (yet not exactly the same with) the default settings of Read the Docs theme's admonitions (see their documentation ). Although users can assign any color to admonitions, light colors are highly recommended since the title color of an admonition is an auto "darker" version of the body color using CSS' brightness filter.

All supported admonition name with default colors are showing below:

Attention

Attention.

Caution

Caution.

Danger

Danger.

Error

Error.

Hint

Hint.

Important

Important.

Note

Note.

Tip

Tip.

Warning

Warning.

canonical_prefix¶

The canonical prefix for each webpage, which can either ends with a / symbol or not. For example, if you set it as https://eg.com/, the webpage (generated from page.rst) will have a canonical url of https://eg.com/page.html.

Note that if you have multiple languages on your website, you may need to include your primary language in the canonical prefix. For example, if your primary language is English (en) and you also have Simplified Chinese (zh_CN) translation, you can use https://eg.com/en/ instead. Simrofy will map all language versions into this primary language canonical url.

favicon¶

The file path (under your html_static_path path, see logo for details) to the website icon (favicon).

github_repo¶

(Only valid when github_user is specified)

Show a Github repo link of https://github.com/GITHUB_USER/GITHUB_REPO instead of your user profile page.

github_user¶

Github username. It will create a icon-weblink to https://github.com/GITHUB_USER on the headbar that allows others visit your Github profile page.

headbar_color¶

Background color of the headbar. Default is royalblue.

New in version 0.4.0.

headbar_height¶

The height of headbar in unit of px. Default is 30

headbar_links¶

Links to be displayed on the headbar. Default is undefined, which displays all webpages (excluding the index.rst and the current one) in alphabetatical order. User may pass a list of filenames (without extension) to handle the output.

For example: 'headbar_links': ['Development', 'Documentation'] will show:

'Development' link only if the user is browsing the 'Documentation' webpage
'Documentation' link only if the user is browsing the 'Development' webpage
Both 'Development' and 'Documentation' links if the user is browsing other webpages.

image_self¶

The photograph of the site owner, which is often seen on portfolio-style websites. Default is undefined . Keep in mind that it is a path under your html_static_path instead of you main folder, see logo for details.

languages¶

A dictionary of display languages for your website. Default is none. You may need to install sphinx-intl and prepare translation .po files to build a multi-language website.

For example, assume that you write your website in English and would like to also provide a Simplified Chinese translation. To build this bilingual website, you need to add a dict of two key-value pairs to your theme option:

# Code in your conf.py
html_theme_options = {
    'languages': {
        'en': 'English',
        'zh_CN': '简体中文'
    }
}

Keys of the dictionary are the abbreviation ('en', 'zh_CN') for languages, and values are the desired displayed text in your website's language menu. For a list of supported languages, please refer to the Sphinx documentation's internationalization (i18n) webpage.

New in version 0.3.0.

logo¶

The logo image file path. Default is undefined, which will display a text hyperlink "Homepage" instead. When a logo path string is assigned, the website will show logo in the mainpage (and sidebar & topbar, if they are enabled).

Note that the file path is the subpath under your html_static_path defined in your conf.py. For example, if you have following lines:

# Code in your conf.py
html_static_path = ["_my_static"]
html_theme_options = {
    'logo': 'logo.png'
}

Then you should put your logo file at _my_static/logo.png.

logo_radius¶

(Only valid when logo is specified)

The radius of the clipping circle to logo. The user input wil be converted into a percentage value and then passed to the circle(...) function of CSS style clip-path. When the value is exact 0.5, it will draw a inscribed-circle viewbox (with respect to the height, if the image is not squared).

Default is undefined, which means the logo will be displayed in normal rectangle shape.

logo_width¶

(Only valid when logo is specified)

The logo width in percentage (for a value <= 1.0 ) or unit of px (for a value > 1.0). Default is 0.8 , or say 80% sidebar width.

people¶

(Only valid when both people_pages and this options are specified)

A dictionary variable that contains the information of people in your team. Default is undefined. An useful example output can be found in the People chapter.

The dictionary should follow a format like (below is an example of external JSON file):

{
    "Leader": {
        "Leader name": {
            "title": "Team leader",
            "address": "Office 1234 in Building A",
            "email": "leader@eg.com",
            "phone": "123-456-7890",
            "photo": "self.jpg"
        }
    },
    "Postdoc": {
        "Postdoc 1": {
            "title": "Postdoc",
            "address": "Office 1234, Building A, Department of Foo and Bar Science, University of Very Long Name that Needs Line Break",
            "email": "one@postdoc.com",
            "phone": "111-222-3333",
            "photo": "self.jpg"
        },
        "Postdoc 2": {
            "title": "Postdoc",
            "address": "Office 1234",
            "email": "two@postdoc.com",
            "phone": "444-555-6666",
            "photo": "self.jpg"
        },

Each entry should be the name of group (e.g. "Leader") and it will be rendered as a <h3> tag in the output webpage (but not included in the toctree). Items under each group are people, where keys are their names (displayed in bold) and values are a dictionary of corresponding personal information.

Personal information includes following fields:

title: The title of the person. Professor, graduate student, visiting scholar, etc.
address: The office address or something similar.
email: The email address of the person. Symbol @ is replaced by text :at: when displayed on the webpage.
phone: The phone number of the person. Since there is no format check, you can use hyphens and brackets or input several phone numbers if needed.
photo: The photo path of the person under the photo_subpath of the static path.

people_pages¶

(Only valid when both people and this options are specified)

A list of webpage filenames (without extension) that appends photos of people in your team. Default is undefined. Only webpages listed here will display those team member photos.

photo_subpath¶

The subpath for photos of team under the html_static_path folder. For example, 'photos/' means photos are under _static/photos/ if we have html_static_path = ['_static']. You may read the logo option for details of static path.

Default is undefined, in which case Sphinx will only search the static path and not dive into deeper subfolders. The tailing forward slash / of the subpath string can be omitted.

sidebar_color¶

The background color of sidebar. Default is color code '#23A97F' (a medium dark green).

sidebar_home_text¶

A short text inserted under the sidebar logo (or the alternative homepage hyperlink if no logo is given). Default is undefined.

sidebar_localtoc¶

The behavior of Table of Contents for current doc page. Note this is different from the whole website file structure (which always shows in the sidebar).

Default is None (hidden). It accepts either 'collapse' or 'expand', which indicates the initial status of the local ToC when opening the webpage.

New in version 0.4.0: A useful feature to show ToC for subfolder docs.

sidebar_position¶

The position of the sidebar. Users can also select:

'left': Display the sidebar on the left. This is the default value.
'right': Display the sidebar on the right.
Any other value will disable the sidebar.

sidebar_toc_exclude¶

A list of rst files that would be excluded from the sidebar tabloe of contents. Each item of the list should be the title of the file. Default is undefined.

sidebar_width¶

The width of the sidebar in unit of px. Default is 240

social_accounts¶

Social accounts information. User can pass a dictionary with a similar structure as follows:

'social_accounts': {
    'facebook': {'user': 'eg-facebook', 'url': 'linkhere'},
    'linkedin': {'user': 'eg-linkedin', 'url': 'linkhere'}
}

Keys of the dictionary should be social media website names. A full list of supported social media names are shown in socialmedia.html, or you can also view it inside the collapsible container below.
Each entry should contain a sub-dictionary that at least has user and url keys. The user string will be displayed as the link text and the url is the link to your social media account webpage.
You need to specify Github user again even if you have done it in github_user.

A full list of supported social media names

{# 
    This is the social media template of Simrofy theme. Simrofy supports social media icons from the Github:

    Original: https://github.com/konsav/social-icons
    Forked & Split: https://github.com/wklchris/social-icons

    Simrofy also allows users to use social media icons not listed here by specifying an icon file path for the website they like.
#}

{% set socials = [
    "500px",
    "aboutme",
    "amazon",
    "android",
    "angellist",
    "apple",
    "behance",
    "bilibili",
    "bookmate",
    "buffer",
    "codepen",
    "coub",
    "delicious",
    "devianart",
    "digg",
    "dribble",
    "dropbox",
    "ello",
    "envato",
    "etsy",
    "etsy-short",
    "evernote",
    "facebook",
    "favorite",
    "flikr",
    "foursquare",
    "github",
    "google+",
    "googledrive",
    "googleplay",
    "habrahabr",
    "instagram",
    "jsfiddle",
    "kickstarter",
    "like",
    "line",
    "line-icon",
    "linkedin",
    "livejournal",
    "mail",
    "map",
    "medium",
    "messenger",
    "ok",
    "periscope",
    "phone",
    "photobucket",
    "pinterest",
    "pinterest-light",
    "pocket",
    "producthunt",
    "quora",
    "reddit",
    "reddit-light",
    "rss",
    "send",
    "send-light",
    "shopify",
    "sketch",
    "skype",
    "slack",
    "slideshare",
    "snapchat",
    "stackoverflow",
    "stumbleupon",
    "swarm",
    "tripadvisor",
    "tumblr",
    "twitter",
    "upwork",
    "viadeo",
    "vimeo",
    "vk",
    "vscogrid",
    "web",
    "windows",
    "wordpress",
    "xing",
    "yelp",
    "youtube",
    "youtube-play"
] %}

Appendices¶

conf.py file¶

The example conf.py file taken from this documentation website:

# Project metadata
project = 'Simrofy'
copyright = '2020, wklchris'
author = 'wklchris'
release = '0.4.1'


# Sphinx configurations
exclude_patterns = [         
    "_build"                 # Ignore _build/ to avoid recursive builds of nbsphinx
]
smartquotes = False          # Show double-dashes clearly
today_fmt = "%Y-%m-%d"       # Date format when using |today| replacement syntax
extensions = [
    'sphinx.ext.mathjax',    # Math equation support
    'recommonmark',          # Markdown support if you don't like reStructuredText
    'sphinxcontrib.bibtex',  # Bibliography support
    'nbsphinx'               # Jupyter notebook (.ipynb) file support
]

bibtex_bibfiles = ['refs.bib']
mathjax3_config = {
    'tex': {'tags': 'ams', 'useLabelIds': True},
}

# For debug only. If installed via pip, using:
#    html_theme = 'sphinx-simrofy-theme'
#    (and remove the html_theme_path line)
html_theme = 'sphinx_simrofy_theme'
html_theme_path = [".."]

# Static paths. Folder for images, CSS, etc.
html_static_path = ["_static"]

# Load external data, if needed
try:
    import json
    with open('_static/people.json', 'r') as f:
        people_json = json.load(f)
except Exception as e:
    print(f"!Exception!: {e}")
    people_json = None
    

# Set internationalization (i18n) for multi-language support
language = 'en'
locale_dirs = ['locale/']  # This can be overwritten by sphinx-intl's "-d" arg.
gettext_compact = False

# Theme options.
# - Read sphinx_simrofy_theme/theme.conf for default values.
html_theme_options = {
    'canonical_prefix': "https://wklchris.github.io/sphinx-simrofy-theme/en/",
    'favicon': "favicon.ico",
    'headbar_links': ['Development', 'Documentation', 'Examples'],
    'sidebar_position': 'left',
    'github_user': 'wklchris',
    'github_repo': 'sphinx-simrofy-theme',
    # 'languages': {'en': 'English', 'zh_CN': '简体中文'},
    'logo': 'logo.png',
    'logo_width': 0.75,
    'logo_radius': 0.5,
    'sidebar_home_text': f'Simrofy v{release}',
    'sidebar_localtoc': 'collapse',
    'sidebar_toc_exclude': ['Examples'],
    'social_accounts': {
        'facebook': {'user': 'eg-facebook', 'url': 'https://linkhere'},
        'linkedin': {'user': 'eg-linkedin', 'url': 'https://linkhere'}
    },
    'people': people_json,
    'people_pages': ['People'],
    'photo_subpath': 'photos/'
}


# Others
templates_path = ['_templates']
rst_epilog = """
.. _Sphinx: https://www.sphinx-doc.org/
.. _sphinxcontrib-bibtex: https://sphinxcontrib-bibtex.readthedocs.io/
.. _recommonmark: https://recommonmark.readthedocs.io/en/latest/
"""