diff --git a/docs/development/documentation/index.md b/docs/development/documentation/index.md index 3f394df..e686edc 100644 --- a/docs/development/documentation/index.md +++ b/docs/development/documentation/index.md @@ -1,32 +1,46 @@ # Documentation -- README.rst -- CHANGELOG.md -- docs/ -- MkDocs -- mkdocstrings +## README +The repository contains a `README.rst` file with basic information.
+It gives a short introduction to the project and links to other relevant files. +## Changelog +The `CHANGELOG.md` is a record of all notable changes made to a project.
+It is structured by each release and divided by additions, changes, and removals.
## MkDocs +[MkDocs](https://www.mkdocs.org/) is a fast and simple static site generator that is used for documentation.
+The source files are written in [Markdown](https://www.markdownguide.org/cheat-sheet/), and configured with `mkdocs.yml`.
+[Material theme](https://squidfunk.github.io/mkdocs-material/) enables +additional features and an elegant design. ### Install -Install the required packages.
-`pip install mkdocs` install MkDocs
-`pip install mkdocs-material` install the material theme +Install the required packages in a python environment.
+💻 `pip install mkdocs` install MkDocs
+💻 `pip install mkdocs-material` install the material theme ### Build -Generate the documentation.
-`mkdocs serve` start the local live version of the documentation
-`mkdocs build` create a folder `site` with the documentation +Generate the documentation locally.
+💻 `mkdocs serve` start the local live version of the documentation
+💻 `mkdocs build` create a folder `site` with the documentation ### Publish #### Manually Publish documentation on **GitHub Pages**.
-`mkdocs gh-deploy` manually deploys the documentation files +💻 `mkdocs gh-deploy` manually deploys the documentation files #### GitHub Action -Deploy the documentation with **GitHub Actions**.
+🐙 Deploy the documentation with **GitHub Actions**.
The file `.github\workflows\gh-pages.yml` creates an automated GitHub workflow.
It is configured to be pushed to the branch `gh-page` and then deployed online.
A commit on the `production` branch triggers the workflow. + +## mkdocstrings +[mkdocstrings](https://mkdocstrings.github.io/) generates automatic +documentation (autodocs) from [Google style docstrings](https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html).
+💻 `pip install mkdocstrings` install mkdocstrings + + +!!! note "Used Icons" + 🐙 GitHub | 💠 git | 📝 File | 💻 Command Line