diff --git a/.gitignore b/.gitignore index 09be0ef..cf30e06 100644 --- a/.gitignore +++ b/.gitignore @@ -69,7 +69,8 @@ instance/ .scrapy # Sphinx documentation -docs/_build/ +docs/build/ +docs/source/reference/ # PyBuilder .pybuilder/ diff --git a/.readthedocs.yaml b/.readthedocs.yaml index 289f0af..6bc548f 100644 --- a/.readthedocs.yaml +++ b/.readthedocs.yaml @@ -9,7 +9,7 @@ build: python: "3.13" sphinx: - configuration: docs/conf.py + configuration: docs/source/conf.py python: install: diff --git a/docs/Makefile b/docs/Makefile index d4bb2cb..d0c3cbf 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -5,8 +5,8 @@ # from the environment for the first two. SPHINXOPTS ?= SPHINXBUILD ?= sphinx-build -SOURCEDIR = . -BUILDDIR = _build +SOURCEDIR = source +BUILDDIR = build # Put it first so that "make" without argument is like "make help". help: diff --git a/docs/index.rst b/docs/index.rst deleted file mode 100644 index fc5b8b4..0000000 --- a/docs/index.rst +++ /dev/null @@ -1,16 +0,0 @@ -.. CCPBioSim-Python-Template documentation master file, created by - sphinx-quickstart on Wed Dec 10 16:51:51 2025. - You can adapt this file completely to your liking, but it should at least - contain the root `toctree` directive. - -CCPBioSim-Python-Template documentation -======================================= - -Add your content using ``reStructuredText`` syntax. See the -`reStructuredText `_ -documentation for details. - - -.. toctree:: - :maxdepth: 2 - :caption: Contents: diff --git a/docs/_static/.gitkeep b/docs/source/_static/.gitkeep similarity index 100% rename from docs/_static/.gitkeep rename to docs/source/_static/.gitkeep diff --git a/docs/_templates/.gitkeep b/docs/source/_templates/.gitkeep similarity index 100% rename from docs/_templates/.gitkeep rename to docs/source/_templates/.gitkeep diff --git a/docs/conf.py b/docs/source/conf.py similarity index 58% rename from docs/conf.py rename to docs/source/conf.py index 496f5ee..65f400d 100644 --- a/docs/conf.py +++ b/docs/source/conf.py @@ -3,17 +3,11 @@ # For the full list of built-in configuration values, see the documentation: # https://www.sphinx-doc.org/en/master/usage/configuration.html -# -- Path setup -------------------------------------------------------------- -import os -import sys +import importlib.metadata import time -# Put the repository root on sys.path so autodoc imports the local package. -DOCS_DIR = os.path.abspath(os.path.dirname(__file__)) -REPO_ROOT = os.path.abspath(os.path.join(DOCS_DIR, "..")) -sys.path.insert(0, REPO_ROOT) - # -- Project information ----------------------------------------------------- +# Change these for your project. project = "CCPBioSim-Python-Template" copyright_first_year = "2025" copyright_owners = "CCPBioSim" @@ -27,25 +21,19 @@ ) copyright = f"{copyright_year_string}, {copyright_owners}. All rights reserved" -version = "" -release = "" +# Read from the installed package, so it matches the release. +release = importlib.metadata.version("example_package") # -- General configuration --------------------------------------------------- extensions = [ - "sphinx.ext.autosummary", - "sphinx.ext.autodoc", "sphinx.ext.mathjax", "sphinx.ext.viewcode", "sphinx.ext.napoleon", "sphinx.ext.intersphinx", "sphinx.ext.extlinks", - "nbsphinx", - "sphinx_copybutton", + "autoapi.extension", ] -# Autosummary (API stubs) -autosummary_generate = True - # Napoleon: Google-style docstrings napoleon_google_docstring = True napoleon_numpy_docstring = False @@ -53,6 +41,25 @@ napoleon_use_rtype = True napoleon_use_ivar = True +# API reference generated from the source by sphinx-autoapi +autoapi_dirs = ["../../example_package"] +autoapi_root = "reference" +autoapi_add_toctree_entry = False +autoapi_member_order = "groupwise" +# Include the __init__ docstring, where the constructor arguments are documented +autoapi_python_class_content = "both" +autoapi_options = [ + "members", + "undoc-members", + "show-inheritance", + "show-module-summary", +] + +# Show type hints in the parameter list rather than the signature +autodoc_typehints = "description" +add_module_names = False +python_maximum_signature_line_length = 88 + templates_path = ["_templates"] source_suffix = ".rst" @@ -62,5 +69,7 @@ exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"] # -- Options for HTML output ------------------------------------------------- -html_theme = "furo" +# The shared CCPBioSim theme. Change github_repo to your repository's name. +html_theme = "ccpbiosim_sphinx_theme" +html_context = {"github_repo": "Python-Template"} html_static_path = ["_static"] diff --git a/docs/source/index.rst b/docs/source/index.rst new file mode 100644 index 0000000..a4e80db --- /dev/null +++ b/docs/source/index.rst @@ -0,0 +1,61 @@ +:html_theme.sidebar_secondary.remove: + +CCPBioSim-Python-Template +========================= + +.. Banner for the home page. Add your logos to _static/logos/ and set + :logo-light: (dark text, for light mode) and :logo-dark: (white text, for + dark mode). See https://ccpbiosim-sphinx-theme.readthedocs.io/ + +.. ccpbiosim-hero:: + :tagline: CCPBioSim-Python-Template + :button: reference/example_package/index | API reference + :github: CCPBioSim/Python-Template + + Short description of your package + +Add an introduction to your package here. See the +`reStructuredText `_ +documentation for details on writing pages. + +Quick start +----------- + +.. tab-set:: + + .. tab-item:: pip + + .. code-block:: bash + + pip install example_package + + .. tab-item:: Conda + + .. code-block:: bash + + conda install -c conda-forge -c ccpbiosim example_package + +Explore the documentation +------------------------- + +.. Add a card for each section of your documentation. + +.. grid:: 1 2 2 2 + :gutter: 3 + + .. grid-item-card:: 📖 API Reference + :link: reference/example_package/index + :link-type: doc + + Reference for the example_package package. + + .. grid-item-card:: 💻 Source Code + :link: https://github.com/CCPBioSim/Python-Template + + The repository on GitHub. + +.. toctree:: + :maxdepth: 2 + :hidden: + + API Reference diff --git a/pyproject.toml b/pyproject.toml index 680ddef..3e73582 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -49,8 +49,7 @@ Documentation = "https://Python-Template.github.io/" [project.optional-dependencies] testing = [ "pytest>=9.0,<10.0", - "pytest-cov>=7.0,<8.0", - "pytest-sugar>=1.1,<2.0" + "pytest-cov>=7.0,<8.0" ] pre-commit = [ @@ -62,9 +61,8 @@ pre-commit = [ docs = [ "sphinx>=9,<10", - "nbsphinx>=0.9,<1.0", - "sphinx_copybutton>=0.5,<1.0", - "furo>=2025.12.19,<2026.0", + "sphinx-autoapi>=3.8,<4.0", + "ccpbiosim-sphinx-theme>=1.3.4,<2.0", "markupsafe>=3.0,<4.0" ]