A Farama Foundation Sphinx documentation theme based on the Furo template.
To learn how to contribute to our projects' documentation go to CONTRIBUTING.md
git clone https://github.com/Farama-Foundation/Celshast.git
cd Celshast
pip install -e .
Add to documentation (conf.py)
html_theme = "furo"
To build and serve the documentation website you should go to the docs/ directory and choose one of the following options.
Option 1: Build once
Build:
make dirhtml
OR
sphinx-build -b dirhtml . _build
Serve the generated website using python (you can choose other http servers):
python -m http.server 8001 --directory _build
Option 2: Automatically build when a change is made
Install sphinx-autobuild
pip install sphinx-autobuild
Build and serve using:
sphinx-autobuild -b dirhtml . _build
Our docs are hosted using GitHub Pages (using gh-pages branch) and we use a GitHub Actions workflow to build the website every time a change is made to the repository.
The following code block shows an example of a yaml file usually named .github/workflows/build-docs.yml that defines the workflow.
name: Deploy Docs
on:
push:
branches: [master]
permissions:
contents: write
jobs:
docs:
name: Generate Website
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- uses: actions/setup-python@v4
with:
python-version: '3.9'
- name: Install docs dependencies
run: pip install -r docs/requirements.txt
- name: Install <Project>
run: pip install -e .
- name: Run some auxiliary scripts, e.g. build environments docs
run: python docs/_scripts/gen_envs_mds.py
- name: Build
run: sphinx-build -b dirhtml -v docs _build
- name: Move 404
run: mv _build/404/index.html _build/404.html
- name: Update 404 links
run: python docs/_scripts/move_404.py _build/404.html
- name: Remove .doctrees
run: rm -r _build/.doctrees
- name: Upload to GitHub Pages
uses: JamesIves/github-pages-deploy-action@v4
with:
folder: _buildCelshast supports documentation versioning using an HTML menu and GitHub Actions. Every page has a JS script that injects an html document with the versions menu, which allows updating older versions without rebuilding.
To enable the menu set the theme option to true in the conf.py file:
html_theme_options = {
"versioning": True,
}With versioning enabled you should have three different GitHub Actions workflows (the names are just an example):
build-docs-dev.yml- Build the docs based on the latest commit in themainbranch, which is an unstable version. The build will be published in the foldermainat thegh-pagesbranch.
name: Build main branch documentation website
on:
push:
branches: [main]
permissions:
contents: write
jobs:
docs:
name: Generate Website
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- uses: actions/setup-python@v4
with:
python-version: '3.9'
- name: Install dependencies
run: pip install -r docs/requirements.txt
- name: Install Gymnasium
run: pip install mujoco && pip install .[atari,accept-rom-license,box2d]
- name: Build Envs Docs
run: python docs/scripts/gen_mds.py && python docs/scripts/gen_envs_display.py
- name: Build
run: sphinx-build -b dirhtml -v docs _build
- name: Move 404
run: mv _build/404/index.html _build/404.html
- name: Update 404 links
run: python docs/_scripts/move_404.py _build/404.html
- name: Remove .doctrees
run: rm -r _build/.doctrees
- name: Upload to GitHub Pages
uses: JamesIves/github-pages-deploy-action@v4
with:
folder: _build
target-folder: main
clean: falsebuild-docs-version.yml- Build the docs' latest version based on a new release (tag). The build will be published in the root folder and a folder named after the version (e.g. 1.0.3) at thegh-pagesbranch.
name: Docs Versioning
on:
push:
tags:
- 'v?*.*.*'
permissions:
contents: write
jobs:
docs:
name: Generate Website for new version
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- uses: actions/setup-python@v4
with:
python-version: '3.9'
- name: Install docs dependencies
run: pip install -r docs/requirements.txt
- name: Install Gymnasium
run: pip install mujoco && pip install .[atari,accept-rom-license,box2d]
- name: Build Envs Docs
run: python docs/_scripts/gen_mds.py && python docs/_scripts/gen_envs_display.py
- name: Build
run: sphinx-build -b dirhtml -v docs _build
- name: Move 404
run: mv _build/404/index.html _build/404.html
- name: Update 404 links
run: python docs/_scripts/move_404.py _build/404.html
- name: Remove .doctrees
run: rm -r _build/.doctrees
- name: Upload to GitHub Pages
uses: JamesIves/github-pages-deploy-action@v4
with:
folder: _build
target-folder: ${{github.ref_name}}
clean: false
- name: Upload to GitHub Pages
uses: JamesIves/github-pages-deploy-action@v4
if: ${{ !contains(github.ref_name, 'a') }}
with:
folder: _build
clean-exclude: |
*.*.*/
mainbuild-manual-docs-version.yml- Build a certain version of the documentation website based on a certain commit. The build will be published in the root folder (if the option latest is enabled) and a folder named after the version (e.g. 1.0.3) at thegh-pagesbranch.
name: Manual Docs Versioning
on:
workflow_dispatch:
inputs:
version:
description: 'Documentation version to create'
required: true
commit:
description: 'Commit used to build the Documentation version'
required: false
latest:
description: 'Latest version'
type: boolean
permissions:
contents: write
jobs:
docs:
name: Generate Website for the new version
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
if: inputs.commit == ''
- uses: actions/checkout@v3
if: inputs.commit != ''
with:
ref: ${{ inputs.commit }}
- uses: actions/setup-python@v4
with:
python-version: '3.9'
- name: Install dependencies
run: pip install -r docs/requirements.txt
- name: Install Gymnasium
run: pip install mujoco && pip install .[atari,accept-rom-license,box2d]
- name: Build Envs Docs
run: python docs/_scripts/gen_mds.py && python docs/_scripts/gen_envs_display.py
- name: Build
run: sphinx-build -b dirhtml -v docs _build
- name: Move 404
run: mv _build/404/index.html _build/404.html
- name: Update 404 links
run: python docs/_scripts/move_404.py _build/404.html
- name: Remove .doctrees
run: rm -r _build/.doctrees
- name: Upload to GitHub Pages
uses: JamesIves/github-pages-deploy-action@v4
with:
folder: _build
target-folder: ${{ inputs.version }}
clean: false
- name: Upload to GitHub Pages
uses: JamesIves/github-pages-deploy-action@v4
if: inputs.latest
with:
folder: _build
clean-exclude: |
*.*.*/
mainTo enable Google Analytics add the following theme option in the conf.py file.
html_theme_options = {
"gtag": "G-6H9C8TWXZ8",
}To enable the donations banner and sidebar button, add the following theme option in the conf.py file.
html_theme_options = {
"donations": True,
}To enable the edit page button, which redirects the user to the source code of the page (i.e. markdown file), add the following context dictionary to the conf.py script.
html_theme_options = {
"source_repository": "https://github.com/Farama-Foundation/<PROJECT>/",
"source_branch": "main",
"source_directory": "docs/",
}html_theme_options = {
"light_logo": "img/gymnasium_black.svg",
"dark_logo": "img/gymnasium_white.svg",
"description": "A standard API for reinforcement learning and a diverse set of reference environments (formerly Gym)",
"image": "img/gymnasium-github.png",
}We provided a set of custom directives that enable us to keep a standard style across the different projects.
This is usually used on the index page of the documentation.
```{project-logo} _static/gymnasium-text.png
:alt: Gymnasium Logo
```
This is usually used on the index page of the documentation after the project logo.
```{project-heading}
A clean customisable Sphinx documentation theme.
```
If you don't want a certain page to have the Next and/or Previous buttons at the bottom you can disable them by adding the following variables to the front matter block of the markdown file:
-
firstpage:- disablesPreviousbutton -
lastpage:- disablesNextbutton
For example:
---
firstpage:
lastpage:
---
Add the following variable to the front matter block of the markdown file:
---
autogenerated:
---
To add an icon next to the page title (H1 or H2, but it needs to be the first) add the following variable to the front matter block of the markdown file:
---
env_icon: [path to icon]
---
The Farama Foundation top menu is built using the response of the API farama.org/api/projects.json. The source code of the API can found here and the source code of the menu here
We use sphinx-gallery to build the tutorials. To add sphinx-gallery you need to add the following code to the conf.py script (assuming that all tutorials are in the folder docs/tutorials). Don't forget to add sphinx-gallery to the docs requirements.
extensions = [
...
"sphinx_gallery.gen_gallery",
]
# -- Generate Tutorials -------------------------------------------------
sphinx_gallery.gen_rst.EXAMPLE_HEADER = """
.. DO NOT EDIT.
.. THIS FILE WAS AUTOMATICALLY GENERATED BY SPHINX-GALLERY.
.. TO MAKE CHANGES, EDIT THE SOURCE PYTHON FILE:
.. "{0}"
.. LINE NUMBERS ARE GIVEN BELOW.
.. rst-class:: sphx-glr-example-title
.. _sphx_glr_{1}:
"""
sphinx_gallery_conf = {
"ignore_pattern": r"__init__\.py",
"examples_dirs": "./tutorials",
"gallery_dirs": "./tutorials",
"show_signature": False,
"show_memory": False,
"min_reported_time": float("inf"),
"filename_pattern": f"{re.escape(os.sep)}run_",
"default_thumb_file": os.path.join(
os.path.dirname(__file__), "_static/img/minari-text.png"
),
}To contribute to the theme you will need to build it. To do that install nox using pip.
pip install nox
And build the testing documentation using the following command.
nox -s docs-live
This project is licensed under the MIT License.