Intorduction

The repository of the documentation of the Regolith project.

• If you're looking for the hosted documentation, you can find it here: https://regolith-docs.readthedocs.io/
• If you're looking for Regolith repository, you can find it here: https://github.com/Bedrock-OSS/regolith/

Contributing

Building Documentation Locally

This repository uses the sphinx documentation generator. The documentation is stored in the docs directory. All commands listed below assume that you are executing them from the docs directory. You can switch to the docs directory by running cd docs.

Installing Documentation Dependencies

To build the documentation you need to install required dependencies.

pip install -r requirements.txt

Building Documentation for the First Time

When you build the documentation for the first time, you need

./make.bat html

Hosting Documentation Locally

You can host the documentation locally with the Python's built-in HTTP server.

python -m http.server --bind localhost -d .\_build\html\

Then you can access the documentation at http://localhost:8000

Rebuilding Documentation

To rebuild the documentation you can run the ./make.bat html but it is recommended to clean the build directory first. You can clean the build directory by running the following command.

rm -r _build\;./make.bat html

Documentation Syntax

We're using the myst-parser to enable the markdown syntax in the documentation. There are a few things that you need to know about the syntax that aren't part of the standard Markdown.

Table of Contents

Table of contents is defined in the index.md file. It is pretty simple to understand. You can read the docs/index.md file to learn by example.

Labels and References

Sphinx lets you define a name for a sectin of the documentation that you can use to create a hyperlink to that section in othe parts of the documentation. Linking pages like that is safer than linking them by their path because if the path changes, the link will still work.

To define a label for a section, you can use the following syntax:

(your-label)=
# Your Section Title
...

To link to that section, you can use the following syntax:

{ref}`Text To Display<your-label>`

When you build the documentation using the make.bat script, the commandline output will print warnings about the labels that aren't used or the references that are broken.

Note and Warning Boxes

You can create a colored box for notes and warnings by using the following syntax:

```{note}
This is a note
```

```{warning}
This is a warning
```

Contribution Process

Simply for the repository, do your changes and create a pull request.