Skip to content

Latest commit

 

History

History
57 lines (39 loc) · 3.91 KB

CONTRIBUTING.md

File metadata and controls

57 lines (39 loc) · 3.91 KB
Raw

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) and built using Sphinx.

Here are some important information about how to contribute to our documentation:

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 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 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. To automatically generate the documentation pages, i.e. .md files, you should use a python script, for example, 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. 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 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 directory (you can use donwload-directory.github.io)
  • 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 for more information.