diff --git a/.gitignore b/.gitignore index 9b356e1e..53054c74 100644 --- 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 index f7bae645..e2db690b 100644 --- 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 index 0558c5f5..3d455c63 100644 --- 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 deleted file mode 100644 index d0c3cbf1..00000000 --- a/docs/Makefile +++ /dev/null @@ -1,20 +0,0 @@ -# Minimal makefile for Sphinx documentation -# - -# You can set these variables from the command line, and also -# from the environment for the first two. -SPHINXOPTS ?= -SPHINXBUILD ?= sphinx-build -SOURCEDIR = source -BUILDDIR = build - -# Put it first so that "make" without argument is like "make help". -help: - @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) - -.PHONY: help Makefile - -# Catch-all target: route all unknown targets to Sphinx using the new -# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). -%: Makefile - @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/docs/make.bat b/docs/make.bat deleted file mode 100644 index 061f32f9..00000000 --- a/docs/make.bat +++ /dev/null @@ -1,35 +0,0 @@ -@ECHO OFF - -pushd %~dp0 - -REM Command file for Sphinx documentation - -if "%SPHINXBUILD%" == "" ( - set SPHINXBUILD=sphinx-build -) -set SOURCEDIR=source -set BUILDDIR=build - -if "%1" == "" goto help - -%SPHINXBUILD% >NUL 2>NUL -if errorlevel 9009 ( - echo. - echo.The 'sphinx-build' command was not found. Make sure you have Sphinx - echo.installed, then set the SPHINXBUILD environment variable to point - echo.to the full path of the 'sphinx-build' executable. Alternatively you - echo.may add the Sphinx directory to PATH. - echo. - echo.If you don't have Sphinx installed, grab it from - echo.https://www.sphinx-doc.org/ - exit /b 1 -) - -%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% -goto end - -:help -%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% - -:end -popd diff --git a/docs/source/background/index.rst b/docs/source/background/index.rst deleted file mode 100644 index 77c3e26d..00000000 --- a/docs/source/background/index.rst +++ /dev/null @@ -1,9 +0,0 @@ -Background -========== -Explanation. Clarification and discussion of key topics. - -.. toctree:: - :maxdepth: 1 - :caption: Contents: - - theory diff --git a/docs/source/conf.py b/docs/source/conf.py index f028ec75..b6fee294 100644 --- 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. @@ -90,6 +89,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 b/docs/source/faq/index.md similarity index 100% rename from docs/source/reference/faq.md rename to docs/source/faq/index.md diff --git a/docs/source/get_started/index.md b/docs/source/get_started/index.md new file mode 100644 index 00000000..0f65d10b --- /dev/null +++ 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 deleted file mode 100644 index 1f8dca96..00000000 --- a/docs/source/get_started/index.rst +++ /dev/null @@ -1,11 +0,0 @@ -Getting Started -=============== -Tutorials. A hands-on introduction to Jupyter Releaser for maintainers. - -.. toctree:: - :maxdepth: 1 - :caption: Contents: - - making_release_from_repo - making_release_from_releaser - generate_changelog diff --git a/docs/source/how_to_guides/index.md b/docs/source/how_to_guides/index.md new file mode 100644 index 00000000..ea42eb79 --- /dev/null +++ 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 deleted file mode 100644 index 522112cc..00000000 --- a/docs/source/how_to_guides/index.rst +++ /dev/null @@ -1,12 +0,0 @@ -How-to Guides -============= -Step-by-step guides. Covers key tasks and operations and common problems - -.. toctree:: - :maxdepth: 1 - :caption: Contents: - - convert_repo_from_releaser - convert_repo_from_repo - write_config - maintain_fork diff --git a/docs/source/index.md b/docs/source/index.md new file mode 100644 index 00000000..da320178 --- /dev/null +++ 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 deleted file mode 100644 index 95a68472..00000000 --- a/docs/source/index.rst +++ /dev/null @@ -1,19 +0,0 @@ -Jupyter Releaser -================ - -.. toctree:: - :maxdepth: 2 - :caption: Contents: - - get_started/index - how_to_guides/index - reference/index - background/index - - -Indices and tables -================== - -* :ref:`genindex` -* :ref:`modindex` -* :ref:`search` diff --git a/docs/source/reference/api_docs.rst b/docs/source/reference/api_docs.md similarity index 51% rename from docs/source/reference/api_docs.rst rename to docs/source/reference/api_docs.md index 8df367aa..7225a6e2 100644 --- a/docs/source/reference/api_docs.rst +++ b/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 new file mode 100644 index 00000000..14e66a76 --- /dev/null +++ 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 new file mode 100644 index 00000000..05b4b682 --- /dev/null +++ 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 deleted file mode 100644 index 2c5d9d04..00000000 --- a/docs/source/reference/index.rst +++ /dev/null @@ -1,13 +0,0 @@ -Reference -========= -Technical reference. Covers tools, components, commands and resources. - -.. toctree:: - :maxdepth: 1 - :caption: Contents: - - releaser_cli - api_docs - configuration - changelog - faq diff --git a/docs/source/reference/releaser_cli.md b/docs/source/reference/releaser_cli.md new file mode 100644 index 00000000..bbca2b73 --- /dev/null +++ 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 deleted file mode 100644 index bd57c06a..00000000 --- a/docs/source/reference/releaser_cli.rst +++ /dev/null @@ -1,6 +0,0 @@ -Releaser CLI -============ - -.. click:: jupyter_releaser.cli:main - :prog: jupyter-releaser - :nested: full diff --git a/docs/source/background/theory.md b/docs/source/reference/theory.md similarity index 100% rename from docs/source/background/theory.md rename to docs/source/reference/theory.md diff --git a/pyproject.toml b/pyproject.toml index 67d899ec..bf1ded3e 100644 --- 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"]