update docs with major overhaul (#38)

Author: joshuadavidthomas

.gitignore

@@ -190,3 +190,6 @@ mediafiles/
 
 # pyright config for nvim-lspconfig
 pyrightconfig.json
+
+# auto-generated apidocs
+apidocs/

CONTRIBUTING.md

@@ -10,7 +10,7 @@ We adhere to Django's Code of Conduct in all interactions and expect all contrib
 
 ## Setup
 
-The following setup steps assume you are using a Unix-like operating system, such as Linux or macOS, and that you have a [supported](README.md#requirements) version of Python installed. If you are using Windows, you will need to adjust the commands accordingly. If you do not have Python installed, you can visit [python.org](https://www.python.org/) for instructions on how to install it for your operating system.
+The following setup steps assume you are using a Unix-like operating system, such as Linux or macOS, and that you have a [supported](https://django-simple-nav.westervelt.dev/en/latest/#requirements) version of Python installed. If you are using Windows, you will need to adjust the commands accordingly. If you do not have Python installed, you can visit [python.org](https://www.python.org/) for instructions on how to install it for your operating system.
 
 1. Fork the repository and clone it locally.
 2. Create a virtual environment and activate it. You can use whatever tool you prefer for this. Below is an example using the Python standard library's `venv` module:

README.md

@@ -1,5 +1,6 @@
 # django-simple-nav
 
+<!-- intro-start -->
 [![PyPI](https://img.shields.io/pypi/v/django-simple-nav)](https://pypi.org/project/django-simple-nav/)
 ![PyPI - Python Version](https://img.shields.io/pypi/pyversions/django-simple-nav)
 ![Django Version](https://img.shields.io/badge/django-3.2%20%7C%204.2%20%7C%205.0-%2344B78B?labelColor=%23092E20)
@@ -13,9 +14,11 @@
 
 - Python 3.8, 3.9, 3.10, 3.11, 3.12
 - Django 3.2, 4.2, 5.0
+<!-- intro-end -->
 
 ## Getting Started
 
+<!-- getting-started-start -->
 1. **Install the package from PyPI.**
 
    ```bash
@@ -33,9 +36,11 @@
        ...,
    ]
    ```
+<!-- getting-started-end -->
 
 ## Usage
 
+<!-- usage-start -->
 1. **Create a navigation definition.**
 
    Define your navigation structure in a Python file. This file can be located anywhere in your Django project, provided it's importable. You can also split the navigations across multiple files if desired.
@@ -199,6 +204,7 @@
    ```
 
 After configuring your navigation, you can use it across your Django project by calling the `django_simple_nav` template tag in your templates. This tag dynamically renders navigation based on your defined structure, ensuring a consistent and flexible navigation experience throughout your application.
+<!-- usage-end -->
 
 ## Documentation
 

RELEASING.md

@@ -1,5 +1,6 @@
 # Releasing a New Version
 
+<!-- releasing-start -->
 When it comes time to cut a new release, follow these steps:
 
 1. Create a new git branch off of `main` for the release.
@@ -52,7 +53,7 @@ When it comes time to cut a new release, follow these steps:
    bumpver update --tag=final
    ```
 
-3. Ensure the [CHANGELOG](CHANGELOG.md) is up to date. If updates are needed, add them now in the release branch.
+3. Ensure the [CHANGELOG](https://github.com/westerveltco/django-simple-nav/CHANGELOG.md) is up to date. If updates are needed, add them now in the release branch.
 
 4. Create a pull request from the release branch to `main`.
 
@@ -73,3 +74,4 @@ When it comes time to cut a new release, follow these steps:
 We try our best to adhere to [Semantic Versioning](https://semver.org/), but we do not promise to follow it perfectly (and let's be honest, this is the case with a lot of projects using SemVer).
 
 In general, use your best judgement when choosing the next version number. If you are unsure, you can always ask for a second opinion from another contributor.
+<!-- releasing-end -->

docs/_static/css/custom.css

@@ -0,0 +1,3 @@
+#django-simple-nav p .reference img {
+  vertical-align: inherit;
+}

docs/changelog.md

@@ -0,0 +1,3 @@
+```{include} ../CHANGELOG.md
+
+```

docs/conf.py

@@ -40,10 +40,10 @@
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
+    "autodoc2",
     "myst_parser",
     "sphinx_copybutton",
     "sphinx_inline_tabs",
-    "sphinx.ext.autodoc",
     "sphinx.ext.napoleon",
 ]
 
@@ -62,6 +62,10 @@
 copybutton_selector = "div.copy pre"
 copybutton_prompt_text = "$ "
 
+# -- Options for autodoc2 -----------------------------------------------------
+autodoc2_packages = [f"../src/{project.replace('-', '_')}"]
+
+autodoc2_render_plugin = "myst"
 
 # -- Options for HTML output -------------------------------------------------
 
@@ -75,6 +79,10 @@
 # so a file named "default.css" will overwrite the builtin "default.css".
 html_static_path = ["_static"]
 
+html_css_files = [
+    "css/custom.css",
+]
+
 html_title = project
 
 html_theme_options = {

docs/development/contributing.md

@@ -0,0 +1,5 @@
+```{include} ../../CONTRIBUTING.md
+
+```
+
+The next section has more information about which `just` commands are available.

docs/development/releasing.md

@@ -0,0 +1,8 @@
+# Releasing
+
+## Releasing a New Version
+
+```{include} ../../RELEASING.md
+:start-after: <!-- releasing-start -->
+:end-before: <!-- releasing-end -->
+```

docs/getting-started.md

@@ -0,0 +1,6 @@
+# Getting Started
+
+```{include} ../README.md
+:start-after: <!-- getting-started-start -->
+:end-before: <!-- getting-started-end -->
+```