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 <[email protected]>

1 files changed, 19 insertions, 0 deletions

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: