Metadata-Version: 2.4
Name: celshast
Version: 0.0.1
Summary: A Farama Foundation Sphinx documentation theme based on Furo.
Author-Email: Farama Foundation <contact@farama.org>, Pradyun Gedam <mail@pradyunsg.me>
License-File: LICENSE
Classifier: Framework :: Sphinx
Classifier: Framework :: Sphinx :: Theme
Classifier: Development Status :: 5 - Production/Stable
Classifier: License :: OSI Approved :: MIT License
Classifier: Environment :: Web Environment
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Operating System :: OS Independent
Classifier: Topic :: Documentation
Classifier: Topic :: Software Development :: Documentation
Project-URL: GitHub, https://github.com/Farama-Foundation/Celshast
Requires-Python: >=3.8
Requires-Dist: beautifulsoup4
Requires-Dist: sphinx<8.0,>=6.0
Requires-Dist: sphinx-basic-ng
Requires-Dist: pygments>=2.7
Requires-Dist: matplotlib
Description-Content-Type: text/markdown

# Celshast

A [Farama Foundation](https://farama.org/) <a href="https://www.sphinx-doc.org/">Sphinx</a> documentation theme based on the [Furo template](https://github.com/pradyunsg/furo).

To learn how to contribute to our projects' documentation go to [CONTRIBUTING.md](CONTRIBUTING.md)

## Install Celshast

```
pip install celshast
```

Or, for development:

```
git clone https://github.com/Farama-Foundation/Celshast.git
cd Celshast
pip install -e .
```

**Add to documentation (conf.py)**

```
html_theme = "celshast"
```

## Build Documentation

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
```

### Workflow to Build Docs

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.

```yaml
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: _build
```

### Workflow to Build Docs with Versioning

Celshast 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](https://github.com/Farama-Foundation/Celshast/blob/main/src/celshast/theme/celshast/static/versioning/versioning_menu.html), which allows updating older versions without rebuilding.

To enable the menu set the theme option to true in the `conf.py` file:

```python
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 the `main` branch, which is an unstable version. The build will be published in the folder `main` at the `gh-pages` branch.

```yaml
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: false
```

- `build-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 the `gh-pages` branch.

```yaml
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: |
            *.*.*/
            main
```

- `build-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 the `gh-pages` branch.

```yaml
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: |
            *.*.*/
            main
```

## Theme Options

### Google Analytics

To enable Google Analytics add the following theme option in the `conf.py` file.

```python
html_theme_options = {
    "gtag": "G-6H9C8TWXZ8",
}
```

### Donations Banner/Button

To enable the donations banner and sidebar button, add the following theme option in the `conf.py` file.

```python
html_theme_options = {
    "donations": True,
}
```

### Edit page button

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.

```python
html_theme_options = {
    "source_repository": "https://github.com/Farama-Foundation/<PROJECT>/",
    "source_branch": "main",
    "source_directory": "docs/",
}
```

### Other Theme options

```python
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",
}
```

## Custom Directives

We provided a set of custom directives that enable us to keep a standard style across the different projects.

### Project Logo

This is usually used on the index page of the documentation.

````
```{project-logo} _static/gymnasium-text.png
:alt: Gymnasium Logo
```
````

### Project Heading

This is usually used on the index page of the documentation after the project logo.

````
```{project-heading}
A clean customisable Sphinx documentation theme.
```
````

## Frontmatter

### Disable Previous page and/or Next page buttons

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:` - disables `Previous` button

- `lastpage:` - disables `Next` button

For example:

```
---
firstpage:
lastpage:
---
```

### Disable page edit button for autogenerated pages

Add the following variable to the front matter block of the markdown file:

```
---
autogenerated:
---
```

### Environment Icon

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]
---
```

### Farama Top Menu

The Farama Foundation top menu is built using the response of the API [farama.org/api/projects.json](https://farama.org/api/projects.json). The source code of the API can found [here](https://github.com/Farama-Foundation/farama.org/blob/main/api/projects.json) and the source code of the menu [here](https://github.com/Farama-Foundation/Celshast/blob/main/src/celshast/theme/celshast/base.html#L238)

## Tutorials

We use [sphinx-gallery](https://sphinx-gallery.github.io/stable/index.html) 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.

```python
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"
    ),
}
```

## Building Theme from source

To contribute to the theme you will need to build it. The toolchain (Python, Node, `uv`, `just`) is pinned in `mise.toml`; install [mise](https://mise.jdx.dev/) and run `mise install` from the repo root to provision matching versions.

```
mise install
just serve
```

`just serve` runs the live-reload docs server bound to `0.0.0.0:8000` so the site is reachable from another device on your LAN (e.g. a phone). To use a different host or port:

```
just serve 127.0.0.1 9000
```

Other recipes in the `Justfile`:

- `just build` — build the docs into `build/docs` once (no live-reload).
- `just lint` — run the pre-commit linters (ruff, prettier, mypy, …).

Each recipe is a thin wrapper around `uvx nox -s <session>`. Nox uses `uv` as its venv backend (configured in `noxfile.py`), so session installs are fast. Available sessions: `docs`, `docs-live`, `lint`, `release`.

For a fuller walkthrough of the contributor workflow — initial setup, linting, the dev server, the release process — see `docs/contributing/workflow.md` (or run `just serve` and browse to it).

## License

This project is licensed under the MIT License.
