Our project currently lacks a proper, version-controlled documentation site. This makes it difficult to maintain and for new contributors to get started.
The Goal:
Migrate our documentation (currently in Word files or the README) to a dedicated documentation site generator like Sphinx or MkDocs.
Why This Is Important:
- Easier to version, review, and collaborate on documentation.
- Generates a clean, professional HTML site.
- Allows us to auto-generate API documentation from our Python docstrings.
- Integrates perfectly with GitHub Pages or Read the Docs for free hosting.
Tasks:
- Choose a generator (MkDocs is recommended for its simplicity and Markdown-based approach).
- Initialize the new documentation structure (e.g., a
docs/ folder).
- Migrate any existing documentation from the README (or other files) into the new structure.
- Set up a clean navigation structure in the config file (e.g.,
mkdocs.yml).
- (Optional but recommended) Set up
mkdocstrings to automatically pull in documentation from the Python code.
- Set up a deployment method (e.g., GitHub Pages).
Acceptance Criteria:
- A
docs/ directory exists with a working mkdocs.yml (or Sphinx conf.py).
- The documentation site builds successfully without errors.
- The site is published and accessible via a GitHub Pages URL.
Our project currently lacks a proper, version-controlled documentation site. This makes it difficult to maintain and for new contributors to get started.
The Goal:
Migrate our documentation (currently in Word files or the README) to a dedicated documentation site generator like Sphinx or MkDocs.
Why This Is Important:
Tasks:
docs/folder).mkdocs.yml).mkdocstringsto automatically pull in documentation from the Python code.Acceptance Criteria:
docs/directory exists with a workingmkdocs.yml(or Sphinxconf.py).