update docs with major overhaul (#38)

westerveltco · Feb 23, 2024 · cf7312f · cf7312f
1 parent 27572da
commit cf7312f
Show file tree

Hide file tree

Showing 13 changed files with 76 additions and 3 deletions.
diff --git a/.gitignore b/.gitignore
@@ -190,3 +190,6 @@ mediafiles/
 
 # pyright config for nvim-lspconfig
 pyrightconfig.json
+
+# auto-generated apidocs
+apidocs/
diff --git a/CONTRIBUTING.md b/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:

diff --git a/README.md b/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
 

diff --git a/RELEASING.md b/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 -->
diff --git a/docs/_static/css/custom.css b/docs/_static/css/custom.css
@@ -0,0 +1,3 @@
+#django-simple-nav p .reference img {
+  vertical-align: inherit;
+}
diff --git a/docs/changelog.md b/docs/changelog.md
@@ -0,0 +1,3 @@
+```{include} ../CHANGELOG.md
+
+```
diff --git a/docs/conf.py b/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 = {

diff --git a/docs/development/contributing.md b/docs/development/contributing.md
@@ -0,0 +1,5 @@
+```{include} ../../CONTRIBUTING.md
+
+```
+
+The next section has more information about which `just` commands are available.
diff --git a/docs/development/releasing.md b/docs/development/releasing.md
@@ -0,0 +1,8 @@
+# Releasing
+
+## Releasing a New Version
+
+```{include} ../../RELEASING.md
+:start-after: <!-- releasing-start -->
+:end-before: <!-- releasing-end -->
+```
diff --git a/docs/getting-started.md b/docs/getting-started.md
@@ -0,0 +1,6 @@
+# Getting Started
+
+```{include} ../README.md
+:start-after: <!-- getting-started-start -->
+:end-before: <!-- getting-started-end -->
+```
diff --git a/docs/index.md b/docs/index.md
@@ -1,11 +1,33 @@
+# django-simple-nav
+
 ```{include} ../README.md
+:start-after: <!-- intro-start -->
+:end-before: <!-- intro-end -->
+```
+
+```{toctree}
+:hidden:
+:maxdepth: 3
+
+getting-started.md
+usage.md
+changelog.md
+```
+
+```{toctree}
+:hidden:
+:maxdepth: 3
+:caption: Reference
 
+apidocs/index.rst
 ```
 
 ```{toctree}
 :hidden:
 :maxdepth: 3
 :caption: Development
 
+development/contributing.md
 development/just.md
+development/releasing.md
 ```
diff --git a/docs/usage.md b/docs/usage.md
@@ -0,0 +1,6 @@
+# Usage
+
+```{include} ../README.md
+:start-after: <!-- usage-start -->
+:end-before: <!-- usage-end -->
+```
diff --git a/pyproject.toml b/pyproject.toml
@@ -57,6 +57,7 @@ docs = [
   "myst-parser",
   "sphinx",
   "sphinx-autobuild",
+  "sphinx-autodoc2",
   "sphinx-copybutton",
   "sphinx-inline-tabs"
 ]