From 4dd2d0cc59b1d720e55442b2c667f0d01b2f687a Mon Sep 17 00:00:00 2001
From: Casper da Costa-Luis <casper.dcl@physics.org>
Date: Tue, 11 Jun 2024 14:54:56 +0100
Subject: [PATCH] docs: explain docs folder layout

---
 docs/source/developer_guide.rst | 21 +++++++++++++++++++++
 1 file changed, 21 insertions(+)

diff --git a/docs/source/developer_guide.rst b/docs/source/developer_guide.rst
index eb434d86b9..bf46802459 100644
--- a/docs/source/developer_guide.rst
+++ b/docs/source/developer_guide.rst
@@ -88,6 +88,27 @@ Rendered
 Building documentation locally
 ------------------------------
 
+Folder layout:
+
+- `README.md` - rendered to `https://github.com/TomographicImaging/CIL`
+- `docs/`
+  - `pages/` - landing (jekyll) source pages
+    - `_config.yml` - jekyll config file
+    - `_data/`
+      - `navigation.yml` - Header section
+      - `services.yml` - "Contact" footer section
+      - `network.yml` - "Thanks" footer section
+    - `XXX.md` - rendered to `https://tomographicimaging.github.io/CIL/XXX`
+  - `source/` - docs (sphinx) source pages
+    - `conf.py` - sphinx config file
+    - `XXX.rst` - rendered to `https://tomographicimaging.github.io/CIL/nightly/XXX`
+  - `docs_environment.yml` - sphinx dependencies
+  - `Gemfile*` - jekyll dependencies
+  - `Makefile` - common build scripts
+    - `mkdemos.py` - downloads demo notebooks to `source/demos/*.ipynb` & creates `source/demos.rst`
+      - `demos-template.rst`
+    - `mkversions.py` - creates `versions.json` used but sphinx docs version switcher
+
 The easiest way to test documentation changes is to open a pull request and `download the rendered documentation from the CI <https://github.com/TomographicImaging/CIL/blob/master/.github/workflows/README.md>`_.
 
 Alternatively, to build the docs locally, you will need a working ``cil`` installation.