From ea9b7a3526d1f8c8efdfd74366f5c9adaf98df82 Mon Sep 17 00:00:00 2001 From: Ian Cullen Date: Wed, 20 May 2026 21:29:44 +0100 Subject: [PATCH 1/6] Ignore generated files Everything in these directories are created by sphinx so we do not need to track them. --- .gitignore | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/.gitignore b/.gitignore index e671fc1..c113576 100644 --- a/.gitignore +++ b/.gitignore @@ -20,3 +20,7 @@ coverage_html_report # Package build files and folders *.egg-info/ **/dist/ + +# Sphinx and documentation auto generated files +docs/build/ +docs/source/generated/ From 41e44166ff1e9177477f9d4ea04f4181f69e3bc0 Mon Sep 17 00:00:00 2001 From: Ian Cullen Date: Wed, 20 May 2026 21:30:47 +0100 Subject: [PATCH 2/6] Add a dependency group for documentation --- pyproject.toml | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/pyproject.toml b/pyproject.toml index 6cba31e..22d837b 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -53,6 +53,12 @@ dev = [ "ruff" ] +docs = [ + "sphinx", + "furo", + "myst-parser", +] + [project.urls] GitHub = "https://github.com/php1ic/nuclearmasses" Changelog = "https://github.com/php1ic/nuclearmasses/blob/main/CHANGELOG.md" From b5bb0ff71c42c49dc2a7681a3fb5bd92a77865a3 Mon Sep 17 00:00:00 2001 From: Ian Cullen Date: Wed, 20 May 2026 22:02:30 +0100 Subject: [PATCH 3/6] Configuration and file required to create a site The docstrings should be enough to remove the need to manually write anything related to the API and low level code. We will still however write some additional content as time goes on. --- docs/source/api.md | 9 +++++++ docs/source/conf.py | 46 ++++++++++++++++++++++++++++++++++ docs/source/getting_started.md | 2 ++ docs/source/index.md | 11 ++++++++ 4 files changed, 68 insertions(+) create mode 100644 docs/source/api.md create mode 100644 docs/source/conf.py create mode 100644 docs/source/getting_started.md create mode 100644 docs/source/index.md diff --git a/docs/source/api.md b/docs/source/api.md new file mode 100644 index 0000000..4d4064c --- /dev/null +++ b/docs/source/api.md @@ -0,0 +1,9 @@ +# API Reference + +```{eval-rst} +.. autosummary:: + :toctree: generated + :recursive: + + nuclearmasses +``` diff --git a/docs/source/conf.py b/docs/source/conf.py new file mode 100644 index 0000000..11061a9 --- /dev/null +++ b/docs/source/conf.py @@ -0,0 +1,46 @@ +# Configuration file for the Sphinx documentation builder. +# +# For the full list of built-in configuration values, see the documentation: +# https://www.sphinx-doc.org/en/master/usage/configuration.html + +from pathlib import Path +import sys +import tomllib + +# Get the root path of the project +ROOT = Path(__file__).resolve().parents[2] + +sys.path.insert(0, str(ROOT / "src")) + +# Project information +with open(ROOT / "pyproject.toml", "rb") as f: + pyproject = tomllib.load(f) + +project = pyproject["project"]["name"] +release = pyproject["project"]["version"] +version = release +copyright = "2026, php1ic" +author = "php1ic" + +# General configuration +extensions = [ + "myst_parser", + "sphinx.ext.autodoc", + "sphinx.ext.autosummary", + "sphinx.ext.napoleon", + "sphinx.ext.viewcode", +] + +napoleon_numpy_docstring = True +napoleon_google_docstring = False +autosummary_generate = True + +exclude_patterns = [] + +source_suffix = { + ".rst": "restructuredtext", + ".md": "markdown", +} + +# Options for HTML output +html_theme = "furo" diff --git a/docs/source/getting_started.md b/docs/source/getting_started.md new file mode 100644 index 0000000..c7719d8 --- /dev/null +++ b/docs/source/getting_started.md @@ -0,0 +1,2 @@ +```{include} ../../README.md +``` diff --git a/docs/source/index.md b/docs/source/index.md new file mode 100644 index 0000000..81c8d23 --- /dev/null +++ b/docs/source/index.md @@ -0,0 +1,11 @@ +# nuclearmasses + +Setting up the framework and pipeline. More complete documentation will follow + +```{toctree} +:maxdepth: 3 + +getting_started +api +``` + From ffa7e59e9f90a51f2293e3f67ac1abfe0e908cbc Mon Sep 17 00:00:00 2001 From: Ian Cullen Date: Wed, 20 May 2026 22:07:08 +0100 Subject: [PATCH 4/6] Add a config file for the read the docs platform This is lifted from their front page with an alteration to use the docs dependency rather than a requirements.txt file. --- .readthedocs.yaml | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) create mode 100644 .readthedocs.yaml diff --git a/.readthedocs.yaml b/.readthedocs.yaml new file mode 100644 index 0000000..6606de1 --- /dev/null +++ b/.readthedocs.yaml @@ -0,0 +1,16 @@ +version: 2 + +build: + os: ubuntu-24.04 + tools: + python: "3.14" + +sphinx: + configuration: docs/source/conf.py + +python: + install: + - method: pip + path: . + extra_requirements: + - docs From 3a724d20f3170260fe356115312065cb57387a97 Mon Sep 17 00:00:00 2001 From: Ian Cullen Date: Wed, 20 May 2026 22:09:42 +0100 Subject: [PATCH 5/6] New CI workflow to generate the docs on each push Might need to tweak the `on` section as we only really want to update the site on a new release. Although we do want to ensure the various files haven't been broken. --- .github/workflows/docs.yml | 28 ++++++++++++++++++++++++++++ 1 file changed, 28 insertions(+) create mode 100644 .github/workflows/docs.yml diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml new file mode 100644 index 0000000..d8ad8b8 --- /dev/null +++ b/.github/workflows/docs.yml @@ -0,0 +1,28 @@ +name: Build Documentation + +on: + pull_request: + push: + branches: + - main + +jobs: + docs: + runs-on: ubuntu-latest + + steps: + - name: Check out repository + uses: actions/checkout@v6 + + - name: Set up Python + uses: actions/setup-python@v6 + with: + python-version: "3.x" + + - name: Install module and doc packages + run: | + python -m pip install --upgrade pip + pip install -e ".[docs]" + + - name: Generate documentation + run: sphinx-build -W -b html docs/source docs/build From 1d16cb3622708fad6af5d92cabe8b9201910319c Mon Sep 17 00:00:00 2001 From: Ian Cullen Date: Wed, 20 May 2026 22:49:15 +0100 Subject: [PATCH 6/6] Convert to an absolute path I want to include the README as-is in the docs website. As a result a relative path to another file in the repo no longer makes sense so we need to use the absolute path. --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 30c7b64..a306ebb 100644 --- a/README.md +++ b/README.md @@ -56,7 +56,7 @@ pip install -e . > [!IMPORTANT] > While every effort is made to maintain a stable API, this module is relatively new so users should not be surprised if there are changes between versions. -> If a breaking change has been introduced, it will always be highlighted in the [CHANGELOG](CHANGELOG.md). +> If a breaking change has been introduced, it will always be highlighted in the [CHANGELOG](https://github.com/php1ic/nuclearmasses/blob/main/CHANGELOG.md). The combination of AME and NUBASE values from all years is available as a single dataframe ```python