Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 2 additions & 1 deletion .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -69,7 +69,8 @@ instance/
.scrapy

# Sphinx documentation
docs/_build/
docs/build/
docs/source/reference/

# PyBuilder
.pybuilder/
Expand Down
2 changes: 1 addition & 1 deletion .readthedocs.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@ build:
python: "3.13"

sphinx:
configuration: docs/conf.py
configuration: docs/source/conf.py

python:
install:
Expand Down
4 changes: 2 additions & 2 deletions docs/Makefile
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down
16 changes: 0 additions & 16 deletions docs/index.rst

This file was deleted.

File renamed without changes.
File renamed without changes.
45 changes: 27 additions & 18 deletions docs/conf.py → docs/source/conf.py
Original file line number Diff line number Diff line change
Expand Up @@ -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"
Expand All @@ -27,32 +21,45 @@
)
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
napoleon_use_param = True
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"
Expand All @@ -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"]
61 changes: 61 additions & 0 deletions docs/source/index.rst
Original file line number Diff line number Diff line change
@@ -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 <https://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html>`_
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 <reference/example_package/index>
8 changes: 3 additions & 5 deletions pyproject.toml
Original file line number Diff line number Diff line change
Expand Up @@ -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 = [
Expand All @@ -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"
]

Expand Down
Loading