Add hatch scripts to build, serve and watch the docs + docs improve…

…ments (#587) * Add `hatch` scripts to build, serve and watch the docs * Convert index.rst to index.md * more fixes * more convert * more improvements * fix rtd * [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci * fix readme * Fix indices and tables * use ref * move faq --------- Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
jupyter-server · Oct 21, 2024 · 42a31f6 · 42a31f6
1 parent 1ab5984
commit 42a31f6
Show file tree

Hide file tree

Showing 22 changed files with 121 additions and 146 deletions.
diff --git a/.gitignore b/.gitignore
@@ -133,6 +133,3 @@ dmypy.json
 
 # macOS
 .DS_Store
-
-# Copied changelog
-docs/source/**/changelog.md
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -52,3 +52,27 @@ To run the Python tests, use:
 ```bash
 pytest
 ```
+
+## Documentation
+
+Contributions can also take the form of fixes and improvements to the documentation.
+
+To build the docs, run:
+
+```bash
+hatch run docs:build
+```
+
+To serve the docs:
+
+```bash
+hatch run docs:serve
+```
+
+It is also possible to automatically watch the docs with the following command:
+
+```bash
+hatch run docs:watch
+```
+
+Then open http://localhost:8000 in your browser to view the documentation.
diff --git a/README.md b/README.md
@@ -30,7 +30,7 @@ See the [adoption guides](https://jupyter-releaser.readthedocs.io/en/latest/how_
 
 GitHub actions scripts are available to draft a changelog, draft a release, publish a release, and check a release.
 
-See the [action details documentation](https://jupyter-releaser.readthedocs.io/en/latest/background/theory.html#action-details) for more information.
+See the [action details documentation](https://jupyter-releaser.readthedocs.io/en/latest/reference/theory.html#action-details) for more information.
 
 The actions can be run on a [fork](https://jupyter-releaser.readthedocs.io/en/latest/how_to_guides/convert_repo_from_releaser.html) of `jupyter_releaser` and target multiple
 repositories, or run as workflows on the [source repositories](https://jupyter-releaser.readthedocs.io/en/latest/how_to_guides/convert_repo_from_repo.html), using

diff --git a/docs/Makefile b/docs/Makefile
diff --git a/docs/make.bat b/docs/make.bat
diff --git a/docs/source/background/index.rst b/docs/source/background/index.rst
diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -13,14 +13,13 @@
 # sys.path.insert(0, os.path.abspath('.'))
 import importlib.metadata
 import os.path as osp
-import shutil
 
 HERE = osp.abspath(osp.dirname(__file__))
 
 # -- Project information -----------------------------------------------------
 
 project = "Jupyter Releaser"
-copyright = "2021, Project Jupyter"
+copyright = "2024, Project Jupyter"
 author = "Project Jupyter"
 
 # The full version, including alpha/beta/rc tags.
@@ -97,6 +96,4 @@
 
 
 def setup(app):
-    dest = osp.join(HERE, "reference", "changelog.md")
-    shutil.copy(osp.join(HERE, "..", "..", "CHANGELOG.md"), dest)
     app.add_css_file("custom.css")
diff --git a/docs/source/reference/faq.md → docs/source/faq/index.md b/docs/source/reference/faq.md → docs/source/faq/index.md
diff --git a/docs/source/get_started/index.md b/docs/source/get_started/index.md
@@ -0,0 +1,12 @@
+# Getting Started
+
+Tutorials. A hands-on introduction to Jupyter Releaser for maintainers.
+
+```{toctree}
+:caption: 'Contents:'
+:maxdepth: 1
+
+making_release_from_repo
+making_release_from_releaser
+generate_changelog
+```
diff --git a/docs/source/get_started/index.rst b/docs/source/get_started/index.rst
diff --git a/docs/source/how_to_guides/index.md b/docs/source/how_to_guides/index.md
@@ -0,0 +1,13 @@
+# How-to Guides
+
+Step-by-step guides. Covers key tasks and operations and common problems
+
+```{toctree}
+:caption: 'Contents:'
+:maxdepth: 1
+
+convert_repo_from_releaser
+convert_repo_from_repo
+write_config
+maintain_fork
+```
diff --git a/docs/source/how_to_guides/index.rst b/docs/source/how_to_guides/index.rst
diff --git a/docs/source/index.md b/docs/source/index.md
@@ -0,0 +1,24 @@
+# Jupyter Releaser
+
+**Jupyter Releaser** contains a set of helper scripts and GitHub Actions to aid in automated releases of Python and npm packages.
+
+```{toctree}
+:maxdepth: 2
+
+get_started/index
+how_to_guides/index
+reference/index
+faq/index
+```
+
+```{toctree}
+:maxdepth: 1
+
+reference/changelog
+```
+
+# Indices and tables
+
+- {ref}`genindex`
+- {ref}`modindex`
+- {ref}`search`
diff --git a/docs/source/index.rst b/docs/source/index.rst
diff --git a/docs/source/reference/api_docs.rst → docs/source/reference/api_docs.md b/docs/source/reference/api_docs.rst → docs/source/reference/api_docs.md
@@ -1,30 +1,39 @@
-API Docs
-========
+# API Docs
 
-Library Functions
------------------
+## Library Functions
+
+```{eval-rst}
 .. automodule:: jupyter_releaser.lib
     :members:
+```
+
+## Python Utility Functions
 
-Python Utility Functions
-------------------------
+```{eval-rst}
 .. automodule:: jupyter_releaser.python
     :members:
 
+```
+
+## NPM Utility Functions
 
-NPM Utility Functions
-------------------------
+```{eval-rst}
 .. automodule:: jupyter_releaser.npm
     :members:
 
+```
 
-Changelog Utility Functions
----------------------------
+## Changelog Utility Functions
+
+```{eval-rst}
 .. automodule:: jupyter_releaser.changelog
     :members:
 
+```
+
+## Global Utility Functions
 
-Global Utility Functions
-------------------------
+```{eval-rst}
 .. automodule:: jupyter_releaser.util
     :members:
+```
diff --git a/docs/source/reference/changelog.md b/docs/source/reference/changelog.md
@@ -0,0 +1,2 @@
+```{include} ../../../CHANGELOG.md
+```
diff --git a/docs/source/reference/index.md b/docs/source/reference/index.md
@@ -0,0 +1,13 @@
+# Reference
+
+Technical reference. Covers tools, components, commands, and resources.
+
+```{toctree}
+:maxdepth: 1
+:caption: Contents:
+
+releaser_cli
+api_docs
+configuration
+theory
+```
diff --git a/docs/source/reference/index.rst b/docs/source/reference/index.rst
diff --git a/docs/source/reference/releaser_cli.md b/docs/source/reference/releaser_cli.md
@@ -0,0 +1,6 @@
+# Releaser CLI
+
+```{click} jupyter_releaser.cli:main
+:prog: jupyter-releaser
+:nested: full
+```
diff --git a/docs/source/reference/releaser_cli.rst b/docs/source/reference/releaser_cli.rst
diff --git a/docs/source/background/theory.md → docs/source/reference/theory.md b/docs/source/background/theory.md → docs/source/reference/theory.md
diff --git a/pyproject.toml b/pyproject.toml
@@ -45,6 +45,7 @@ content-type = "text/markdown"
 [project.optional-dependencies]
 docs = [
   "sphinx",
+  "sphinx-autobuild",
   "sphinx-copybutton",
   "pip",
   "myst-parser",
@@ -73,7 +74,9 @@ validate-bump = false
 [tool.hatch.envs.docs]
 features = ["docs"]
 [tool.hatch.envs.docs.scripts]
-build = "make -C docs html SPHINXOPTS='-W'"
+build = "sphinx-build -W -b html docs/source docs/build/html"
+serve = "python -m http.server --directory docs/build/html"
+watch = "sphinx-autobuild -W -b html docs/source docs/build/html --host 0.0.0.0"
 
 [tool.hatch.envs.test]
 features = ["test"]