From 170f8d18a64bb9b84141087d9b684d9362bff6cd Mon Sep 17 00:00:00 2001
From: erinhmclark <erinhannahmary.clark@gmail.com>
Date: Thu, 16 Jan 2025 20:46:10 +0000
Subject: [PATCH] Add instructions to README.md, include build directories in
 .gitignore and do a bit more tidying,

---
 .gitignore                     |  2 ++
 README.md                      | 42 ++++++++++++++++++++++++++++++++++
 docs/source/configurations.rst |  2 --
 docs/source/index.rst          |  2 +-
 4 files changed, 45 insertions(+), 3 deletions(-)

diff --git a/.gitignore b/.gitignore
index f545ac2..7c6bf08 100644
--- a/.gitignore
+++ b/.gitignore
@@ -30,3 +30,5 @@ logs*
 *.csv
 archived/
 dist*
+docs/_build/
+docs/source/autoapi/
diff --git a/README.md b/README.md
index 90da1af..1bd6ddd 100644
--- a/README.md
+++ b/README.md
@@ -76,6 +76,8 @@ Clone and run:
 2. `poetry install`
 3. `poetry run python -m src.auto_archiver --config secrets/orchestration.yaml`
 
+Note: Add the plugin [poetry-shell-plugin](https://github.com/python-poetry/poetry-plugin-shell) and run `poetry shell` to activate the virtual environment.
+This allows you to run the auto-archiver without the `poetry run` prefix.
 
 </details><br/>
 
@@ -286,6 +288,46 @@ manual release to docker hub
   * `docker image tag auto-archiver bellingcat/auto-archiver:latest`
   * `docker push bellingcat/auto-archiver`
 
+
+### Building the Docs
+
+The documentation is built using [Sphinx](https://www.sphinx-doc.org/en/master/) and [AutoAPI](https://sphinx-autoapi.readthedocs.io/en/latest/) and hosted on ReadTheDocs.
+To build the documentation locally, run the following commands:
+
+**Install required dependencies:**
+- Install the docs group of dependencies: 
+```shell
+# only the docs dependencies
+poetry install --only docs
+
+# or for all dependencies 
+poetry install
+```
+- Either use [poetry-plugin-shell](https://github.com/python-poetry/poetry-plugin-shell) to activate the virtual environment: `poetry shell`
+- Or prepend the following commands with `poetry run`
+
+**Create the documentation:**
+- Build the documentation: 
+```
+# Using makefile (Linux/macOS):
+make -C docs html
+
+# or using sphinx directly (Windows/Linux/macOS):
+sphinx-build -b html docs/source docs/_build/html
+```
+- If you make significant changes and want a fresh build run: `make -C docs clean` to remove the old build files.
+
+**Viewing the documentation:**
+```shell
+# to open the documentation in your browser.
+open docs/_build/html/index.html
+
+# or run autobuild to automatically update the documentation when you make changes
+sphinx-autobuild docs/source docs/_build/html
+```
+
+
+
 #### RELEASE
 * update version in [version.py](src/auto_archiver/version.py)
 * go to github releases > new release > use `vx.y.z` for matching version notation
diff --git a/docs/source/configurations.rst b/docs/source/configurations.rst
index 3fb482c..a466869 100644
--- a/docs/source/configurations.rst
+++ b/docs/source/configurations.rst
@@ -30,6 +30,4 @@ Configs
 This section of the documentation will show the custom configurations for the individual steps of the tool.
 
 
-.. include:: configs.rst
-
 
diff --git a/docs/source/index.rst b/docs/source/index.rst
index 22b6e1e..d6437e1 100644
--- a/docs/source/index.rst
+++ b/docs/source/index.rst
@@ -20,8 +20,8 @@ Auto Archiver documentation
    :hidden:
    :caption: Contents:
 
+   user_guidelines
    developer_guidelines
    configurations
-   user_guidelines
    configs