Pages update

[Gabe-Levin]

Merging latest changes and fixing #90

[github-actions]

PR Deployment Details:
🚀 PR deployed to https://pl6prmd2y0.execute-api.us-east-1.amazonaws.com/

[andresfchamorro]

Small changes to improve docs and build workflow

• Changed structure of docs. Root file is readme.md and every file needs to be nested within docs (for sphinx to work).
• Removed sphinx.ext.autodoc, but kept sphinx.ext.napoleon and sphinxcontrib.apidoc extensions to build rst file (docstrings).
• Edited docstring from lib.py
• Re-ran notebooks and added folium maps
• Moved notebooks/user-docs to docs/user-docs. This makes it easier to build them without using symbolic links which don't work on windows.
• Changed github action to deploy docs (will be tested once this PR is merged)
• Added jupyter-book to .toml dependencies
• Markdown changes to improve figure captions
• New instructions for how to build docs locally and make changes in readme:

Environment Setup

To install the package and docs dependencies:

conda create -n book python=3.11
conda activate book
pip install poetry
cd space2stats_api/src
poetry install --with docs # Installs space2stats, dependencies and jupyter-book
pip install folium matplotlib mapclassify # for additional notebook visualizations

To build the documentation locally, run the following command:

sphinx-build docs _build/html -b html

Contributing

A Github Action is used to automatically build and deploy the documentation to Github Pages. To contribute to the documentation, please follow the steps below:

1. Create a new branch from the latest main.

   git checkout -b new_docs

2. Make changes to the documentation, e.g: markdown files, and table of contents (docs/_toc.yml).

3. Build the documentation locally to ensure it renders correctly.

4. Commit, push the changes to your branch and create a pull request.

   git add .
   git commit -m "Update documentation"
   git push origin new_docs

The site will be updated automatically once the branch is merged to main.