celshast 0.0.1__tar.gz

celshast-0.0.1/CODE_OF_CONDUCT.md

@@ -0,0 +1,61 @@
+# Farama Foundation Code of Conduct
+
+The Farama Foundation is dedicated to providing a harassment-free experience for
+everyone, regardless of gender, gender identity and expression, sexual
+orientation, disability, physical appearance, body size, age, race, or
+religion. We do not tolerate harassment of participants in any form.
+
+This code of conduct applies to all Farama Foundation repositories (including Gist
+comments) both online and off. Anyone who violates this code of
+conduct may be sanctioned or expelled from these spaces at the
+discretion of the moderators.
+
+We may add additional rules over time, which will be made clearly
+available to participants. Participants are responsible for knowing
+and abiding by these rules.
+
+## Our Standards
+
+Members of the Farama Foundation community are **open**, **inclusive**, and **respectful**.
+Examples of behavior that contributes to a positive environment for our community include:
+
+- **Being open**. Members of the community are open to collaboration, whether it's on issues, PRs, problems, or otherwise
+- **Focusing on what is best for the community**. We're respectful of the processes set forth in the community, and we work within them to
+  improve the community.
+- **Being respectful of differing viewpoints and experiences.** We're receptive to constructive comments and criticism,
+  as the experiences and skill sets of other members contribute to the whole of our efforts.
+- **Showing empathy.** We're attentive in our communications, and we're tactful when approaching differing views.
+- **Being respectful.** We're respectful of differing opinions, viewpoints, experiences, and efforts.
+- **Gracefully accepting constructive criticism.** When we disagree, we are courteous in raising our issues.
+- **Using welcoming and inclusive language.** We're accepting of all who wish to take part in our activities, fostering
+  an environment where anyone can participate and everyone can make a difference.
+
+Examples of unacceptable behavior include:
+
+- Harassment of any participants in any form.
+- The use of sexual language or imagery, and sexual attention or advances of any kind.
+- Insults, put downs, or jokes that are based upon stereotypes, that are exclusionary, or that hold others up for ridicule.
+- Publishing others' private information, such as a physical or email address, without explicit permission.
+- Incitement of violence or harassment towards any individual, including encouraging a person to commit suicide or to engage in self-harm.
+- Sustained disruption of online community discussions, in-person presentations, or other in-person events.
+- Creating additional online accounts in order to harass another person or circumvent a ban
+- Other conduct which could reasonably be considered inappropriate in a professional setting including people of many different backgrounds.
+
+Members asked to stop any inappropriate behavior are expected to comply immediately.
+
+## Consequences
+
+If a participant engages in behavior that violates this code of conduct, the Farama Foundation team may take any action they deem
+appropriate, including warning the offender or expulsion from the community.
+
+Thank you for helping make this a welcoming, friendly community for everyone.
+
+## License
+
+This Code of Conduct is licensed under the `Creative Commons Attribution-ShareAlike 3.0 Unported License
+<https://creativecommons.org/licenses/by-sa/3.0/>`\_.
+
+## Attribution
+
+This Code of Conduct is adapted from `Python's Code of Conduct <https://www.python.org/psf/conduct/>`_, which is under a `Creative Commons License
+<https://creativecommons.org/licenses/by-sa/3.0/>`_.

celshast-0.0.1/CONTRIBUTING.md

@@ -0,0 +1,57 @@
+# Contribute to Farama projects documentation
+
+Thank you for considering contributing to our documentation! A good
+documentation is vital for any project and empowers those that use it.
+
+Our documentation is written in [MyST (Markedly Structured Text)](https://myst-parser.readthedocs.io/en/latest/) and built using [Sphinx](https://www.sphinx-doc.org/en/master/).
+
+Here are some important information about how to contribute to our documentation:
+
+- [Build Documentation](./README.md#build-documentation)
+- [Write Documentation](#write-documentation)
+- [Write Environments Documentation](#write-environments-documentation)
+- [Write Tutorials](#write-tutorials)
+- [Sphinx Theme options](./README.md#theme-options)
+- [Frontmatter options](./README.md#frontmatter)
+- [Create Documentation Website](#create-a-documentation-website)
+
+## Write Documentation
+
+Here are some guidelines to follow when writing documentation:
+
+1. Use **clear** and **concise** language. Avoid jargon and technical terms when possible.
+2. Use **Google-style** Python docstrings.
+3. Use the reStructuredText markup language inside docstrings.
+4. Use [`autodoc`](https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html) to automatically generate documentation from your code.
+5. Use the MyST markdown (using the .md file extension) for documentation files inside the `docs/` directory.
+6. Use scripts to generate environments documentation.
+7. Use [`sphinx-gallery`](https://sphinx-gallery.github.io/stable/index.html) to include tutorials in your documentation.
+
+## Write Environments Documentation
+
+Environment documentation varies from project to project and sometimes from environment type.
+
+Some environments, for example, Atari, require you to directly edit the Markdown file, however those are rare situations that should be **avoided**.
+
+For most cases environments should be documented using a docstring inside the entry point class, [example](https://github.com/Farama-Foundation/Gymnasium/blob/5bb67ee69d8fc21fafe4147fdcafa1e1daf158c4/gymnasium/envs/box2d/bipedal_walker.py#L104). To automatically generate the documentation pages, i.e. `.md` files, you should use a python script, for example, [docs/scripts/gen_mds.py](https://github.com/Farama-Foundation/Gymnasium-Robotics/blob/main/docs/scripts/gen_mds.py).
+
+## Write Tutorials
+
+We use Sphinx-Gallery to build the tutorials inside the docs/tutorials directory.
+
+To convert Jupyter Notebooks to Python tutorials you can use [this script](./starter_kit/_scripts/ipynb_to_gallery.py).
+To convert cells outputting static images, like `<img src="../_static/img/tutorials/my_image.png" alt="My image description">`, they need to be in single Mardown cell and have an `alt` text.
+
+If you want Sphinx-Gallery to execute the tutorial (which adds outputs and plots) then the file name should start with run\_. Note that this adds to the build time so make sure the script doesn't take more than a few seconds to execute.
+
+Go to [Sphinx-Gallery documentation](https://sphinx-gallery.github.io/stable/syntax.html) for more information.
+
+## Create a Documentation website
+
+- Create a directory named `docs` in the root directory of the project's repository
+- **Copy** the contents inside the [start_kit](./starter_kit/) directory (you can use [donwload-directory.github.io](https://download-directory.github.io/?url=https%3A%2F%2Fgithub.com%2FFarama-Foundation%2FCelshast%2Ftree%2Fmain%2Fstarter_kit))
+- **Paste** them inside the new `docs` directory
+- Replace `<PROJECT>` and `<PROJECT_LOW>` with the name of the project, e.g. Gymnasiun would replace `<PROJECT>` with `Gymnasium` and `<PROJECT_LOW>` with `gymnasium`. You will find these placeholders inside files and in file names without the angle brackets.
+- Replace the images and svg files inside `_static/img` with the ones corresponding to the project.
+- Add content to the documentation.
+- Add GitHub Actions workflows to build the website. Go [here](./README.md#workflow-to-build-docs) for more information.

celshast-0.0.1/Justfile

@@ -0,0 +1,11 @@
+default:
+    @just --list
+
+serve host="0.0.0.0" port="8000":
+    uvx nox -s docs-live -- --host {{host}} --port {{port}}
+
+build:
+    uvx nox -s docs
+
+lint:
+    uvx nox -s lint

celshast-0.0.1/LICENSE

@@ -0,0 +1,19 @@
+Copyright (c) 2020 Pradyun Gedam <mail@pradyunsg.me> & Copyright (c) 2023 Farama Foundation
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to
+deal in the Software without restriction, including without limitation the
+rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
+sell copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+IN THE SOFTWARE.

celshast-0.0.1/PKG-INFO

@@ -0,0 +1,518 @@
+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.