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 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/ 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 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 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 +``` + 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"