From 8f2067b0f2f9cd6001a9565f8da4590f5b414f1e Mon Sep 17 00:00:00 2001 From: Hassan Abouelela Date: Sun, 29 May 2022 16:27:22 +0400 Subject: Document The Docs Folder Add a brief explanation about each item in the docs folder, to help contributors navigate and understand what each part does. Signed-off-by: Hassan Abouelela --- docs/README.md | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) (limited to 'docs/README.md') diff --git a/docs/README.md b/docs/README.md index 16c9e8cc..89124d5e 100644 --- a/docs/README.md +++ b/docs/README.md @@ -18,6 +18,25 @@ poetry run task docs The output will be in the [`/docs/build`](.) directory. +## Layout +The docs folder has a few moving components, here's a brief description of each: + +- `_static`: This folder includes extra resources that are copied blindly by sphinx into the result + making it perfect for resources such as custom CSS or JS. +- `_templates` & `pages`: Both are considered HTML templates, and passed to Sphinx as `templates_path`. + The difference between them is that `_templates` is only used to provide templates and overrides that + are used by other pages, while `pages` are full-blown independent pages that will be included in the + result. Files in `pages` are passed to Sphinx as `html_additional_pages`, and will maintain the same + structure as the folder. That is to say, a file such as `pages/a/b.html` will create `https://bot-core/a/b.html`. +- `changelog.rst`: This contains a list of all the project's changes. Please refer to [Changelog](#Changelog) + below for more info. +- `index.rst`: The main content for the project's homepage. +- `conf.py`: Configuration for Sphinx. This includes things such as the project name, version, + plugins and their configuration. +- `utils.py`: Helpful function used by `conf.py` to properly create the docs. +- `netliy_build.py`: Script which downloads the build output in netlify. Refer to [Static Netlify Build](#static-builds) + + ## Versions The project supports building all different versions at once using [sphinx-multiversion][multiversion] after version `v7.1.0`. You can run the following command to achieve that: -- cgit v1.2.3