From cf7312f752fe1a0c5a6ce889226c2e2bae8a5421 Mon Sep 17 00:00:00 2001 From: Josh Thomas Date: Fri, 23 Feb 2024 12:57:29 -0600 Subject: [PATCH] update docs with major overhaul (#38) --- .gitignore | 3 +++ CONTRIBUTING.md | 2 +- README.md | 6 ++++++ RELEASING.md | 4 +++- docs/_static/css/custom.css | 3 +++ docs/changelog.md | 3 +++ docs/conf.py | 10 +++++++++- docs/development/contributing.md | 5 +++++ docs/development/releasing.md | 8 ++++++++ docs/getting-started.md | 6 ++++++ docs/index.md | 22 ++++++++++++++++++++++ docs/usage.md | 6 ++++++ pyproject.toml | 1 + 13 files changed, 76 insertions(+), 3 deletions(-) create mode 100644 docs/_static/css/custom.css create mode 100644 docs/changelog.md create mode 100644 docs/development/contributing.md create mode 100644 docs/development/releasing.md create mode 100644 docs/getting-started.md create mode 100644 docs/usage.md diff --git a/.gitignore b/.gitignore index 9999ab1..cf6bc5d 100644 --- 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 index 4c54ff8..21cb19e 100644 --- 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 index b60a2c0..b507cc1 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,6 @@ # django-simple-nav + [![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 + ## Getting Started + 1. **Install the package from PyPI.** ```bash @@ -33,9 +36,11 @@ ..., ] ``` + ## Usage + 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. + ## Documentation diff --git a/RELEASING.md b/RELEASING.md index da2e6a1..c90bc66 100644 --- a/RELEASING.md +++ b/RELEASING.md @@ -1,5 +1,6 @@ # Releasing a New Version + 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. + diff --git a/docs/_static/css/custom.css b/docs/_static/css/custom.css new file mode 100644 index 0000000..b572723 --- /dev/null +++ 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 new file mode 100644 index 0000000..d9e79ba --- /dev/null +++ b/docs/changelog.md @@ -0,0 +1,3 @@ +```{include} ../CHANGELOG.md + +``` diff --git a/docs/conf.py b/docs/conf.py index 8da4e9e..3720ecc 100644 --- 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 new file mode 100644 index 0000000..9dc9c51 --- /dev/null +++ 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 new file mode 100644 index 0000000..5aa0c21 --- /dev/null +++ b/docs/development/releasing.md @@ -0,0 +1,8 @@ +# Releasing + +## Releasing a New Version + +```{include} ../../RELEASING.md +:start-after: +:end-before: +``` diff --git a/docs/getting-started.md b/docs/getting-started.md new file mode 100644 index 0000000..a8e22ed --- /dev/null +++ b/docs/getting-started.md @@ -0,0 +1,6 @@ +# Getting Started + +```{include} ../README.md +:start-after: +:end-before: +``` diff --git a/docs/index.md b/docs/index.md index 9385dba..78e0167 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,5 +1,25 @@ +# django-simple-nav + ```{include} ../README.md +:start-after: +:end-before: +``` + +```{toctree} +:hidden: +:maxdepth: 3 + +getting-started.md +usage.md +changelog.md +``` + +```{toctree} +:hidden: +:maxdepth: 3 +:caption: Reference +apidocs/index.rst ``` ```{toctree} @@ -7,5 +27,7 @@ :maxdepth: 3 :caption: Development +development/contributing.md development/just.md +development/releasing.md ``` diff --git a/docs/usage.md b/docs/usage.md new file mode 100644 index 0000000..673b19d --- /dev/null +++ b/docs/usage.md @@ -0,0 +1,6 @@ +# Usage + +```{include} ../README.md +:start-after: +:end-before: +``` diff --git a/pyproject.toml b/pyproject.toml index 0515b86..b788da2 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -57,6 +57,7 @@ docs = [ "myst-parser", "sphinx", "sphinx-autobuild", + "sphinx-autodoc2", "sphinx-copybutton", "sphinx-inline-tabs" ]