Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

📝 Documentate how to build the doc #229

Merged
merged 9 commits into from
Jun 26, 2024
3 changes: 3 additions & 0 deletions docs/CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,9 @@

- ([218](https://github.com/Gunivers/Bookshelf/pull/218)) Enhanced speed of factorial function in `bs.math`.

### 📄 Documentation
- ([215](https://github.com/Gunivers/Bookshelf/issues/215)) There is now documentation about the documentation (kind of metadocumentation?).

---

## 📦 Bookshelf - 2.1.0
Expand Down
50 changes: 50 additions & 0 deletions docs/contribute/documentation.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,50 @@
---
html_theme.sidebar_secondary.remove: true
---

# 📝 Documentation

The primary objective of Bookshelf is to streamline the datapack development process and ensure accessibility. To achieve this, it is crucial that the library is thoroughly documented.
We have dedicated significant effort to creating this comprehensive documentation website.
Moreover, we request that every new feature contribution be accompanied by appropriate documentation.

This page aims to give some information on how to contribute to the documentation itself.

## ⚙️ Install the required tools

Bookshelf documentation requires Python.
If you are not familiar with this programming language, don't worry, you don't have to use it.
But to be able to build the documentation locally, you still need to install it.
For that, you can download version 3.12 or higher on the [Python website](https://www.python.org/downloads/).
After having installed Python and cloned the Bookshelf repository, navigate to the `/docs` folder and open a terminal (or Powershell if you are on Windows).
Then, execute this command:

```shell
pip install -r requirements.txt -U
```

This command will install all the required dependencies, especially [Sphinx](https://www.sphinx-doc.org/en/master/) and [Myst Parser](https://myst-parser.readthedocs.io/en/latest/intro.html) that enable the generation of the documentation website from the different Markdown files.

## ✍️ Write the documentation

The documentation is mainly written in Markdown, extended by Myst Parser.
You can find the documentation of Myst Parser [here](https://myst-parser.readthedocs.io/en/latest/intro.html).
To write a new documentation page or to document a new feature, you can simply take as example the existing pages/features.

All the images are stored into the `/docs/_imgs` folder.

## 🔨 Build the documentation locally

To ensure your documentation contribution works correctly, you can build and verify it locally on your computer.
To do this, navigate to the `/docs` folder and open a terminal (or Powershell if you are on Windows).
Then, execute this command:

```shell
# For Windows:
./make html
# For other OSs:
make html
```

You can now find the built documentation inside the `/docs/_build/html` folder.
Open the `index.html` with your browser to see your changes.
1 change: 1 addition & 0 deletions docs/contribute/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -31,6 +31,7 @@ nomenclature
shared-data
file-format
metadata
documentation
contribution-validation
````

Expand Down