useblocks-theme

This repository contains the theme for all Useblock documentation sites.

NOTE:

• Useblocks uses the Sphinx-Immaterial theme so ensure that the theme is already installed and applied.
• Install sphinx_immaterial by running this command: pip install sphinx-immaterial.
• Then activate the theme by adding it to the extension variable under conf.py: extensions = ["sphinx_immaterial"]
• And change the html_theme variable to html_theme = "sphinx_immaterial"

Installation

To install the files from this repository, you must have Git installed.

• Change directory to your root directory if you are in a subdirectory.
• Add the files from this repository (ub_theme) as a dependency to your docs project:

  git subtree add --prefix docs/ub_theme/ https://github.com/useblocks/ub_theme.git main --squash

Updating the ub_theme folder in a documentation project

You can update the ub_theme repository by running the following command:

git subtree pull --prefix docs/ub_theme/ https://github.com/useblocks/ub_theme.git main --squash

• git subtree pull: The pull option under git subtree allows you to sync changes between the subproject repository and the copy of it in the other documentation project.
• --prefix [folder_path]: The --prefix option allows you to set the value for where you want to store the subproject repository files. E.g. docs/ub_theme.
• https://github.com/useblocks/ub_theme.git main is the remote repository link and branch you want to copy from.
• --squash is the flag that combines all the commits from the subproject repository into one commit for the parent project repository.

Configuration

You must configure the following in the conf.py file of the Sphinx documentation project.

• In order to import the ub_theme package, Python searches through the directories on sys.path looking for the package subdirectory.
  • Add the parent path of the ub_theme folder to sys.path.

    import os
    import sys
    sys.path.append(os.path.abspath(".")) # Example if `ub_theme` folder is in the same folder as the `conf.py` file

• Add the ub_html_theme_options to your conf.py:
  • Import the theme options for Useblocks.

    from ub_theme.conf import ub_html_theme_options

  • Set it as the value for the ub_html_theme_options variable.

    html_theme_options = ub_html_theme_options

• Add the custom template changes folder to the templates_path variable.

  templates_path = ["_templates", "ub_theme/templates"]

• Add custom CSS changes:
  • Add the folder containing the CSS files to the html_static_path variable.

    html_static_path = ["ub_theme/css"]

  • Add the custom CSS files to the html_css_files variable.

    html_css_files = ["ub-theme.css"]

• Add custom JS changes:
  • Add the folder containing the JS files to the html_static_path variable.

    html_static_path = ["ub_theme/js"]

  • Add the custom JS files to the html_js_files variable.

    html_js_files = ["ub-theme.js"]

The final configuration should look like below:

import os
import sys

sys.path.append(os.path.abspath("."))

from ub_theme.conf import ub_html_theme_options

extensions = [
    "sphinx_immaterial",
]

templates_path = ["_templates", "ub_theme/templates"]

html_theme = "sphinx_immaterial"
html_theme_options = ub_html_theme_options

# You can add other Sphinx-Immaterial theme options like below
other_options = {
    "repo_url": "https://github.com/useblocks/ub_theme",
    "repo_name": "useblocks-theme",
    "repo_type": "github",
}
html_theme_options.update(other_options)

html_static_path = ["_static", "ub_theme/css", "ub_theme/js"]
html_css_files = ["ub-theme.css"]
html_js_files = ["ub-theme.js"]

Changelog

• 13.02.2023 - Updated README.md and text font to Recursive. Added SUBTREE.md file.
• 23.01.2023 - Updated CSS for theme, changelog and conf.py
• 13.01.2023 - Updated CSS stylesheets and docs on how to apply the theme customization.
• 28.12.2022 - Setup and added the initial Useblocks theme codes.