Skip to content

Commit 1ed6db6

Browse files
andreascaglioniandreascaglioni
committed
add docs (+ pyproject.toml options)
1 parent e9d769e commit 1ed6db6

File tree

6 files changed

+275
-3
lines changed

6 files changed

+275
-3
lines changed

‎docs/Makefile‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
SPHINXBUILD = sphinx-build
2+
SOURCEDIR = .
3+
BUILDDIR = _build
4+
5+
.PHONY: html clean
6+
7+
html:
8+
$(SPHINXBUILD) -M html "$(SOURCEDIR)" "$(BUILDDIR)"
9+
10+
clean:
11+
rm -rf "$(BUILDDIR)"

‎docs/api.rst‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
API Reference
2+
=============
3+
4+
This section documents the public API exposed by the `python-project-template` package.
5+
6+
.. autosummary::
7+
:toctree: _autosummary
8+
9+
python_project_template.calculator
10+
python_project_template.operations
11+
python_project_template.registry
12+
python_project_template.exceptions
13+
python_project_template.utils
14+
15+
16+
17+
.. automodule:: python_project_template.calculator
18+
:members:
19+
:undoc-members:
20+
:noindex:
21+
:show-inheritance:
22+
23+
.. automodule:: python_project_template.operations
24+
:members:
25+
:noindex:
26+
:undoc-members:
27+
28+
.. automodule:: python_project_template.registry
29+
:members:
30+
:noindex:
31+
32+
.. automodule:: python_project_template.exceptions
33+
:members:
34+
:noindex:
35+
36+
.. automodule:: python_project_template.utils
37+
:members:
38+
:noindex:

‎docs/conf.py‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
import os
2+
import sys
3+
4+
# -- Path setup --------------------------------------------------------------
5+
# Ensure the project package is importable for autodoc (assumes src layout)
6+
sys.path.insert(0, os.path.abspath("../src"))
7+
8+
# -- Project information -----------------------------------------------------
9+
project = "python-project-template"
10+
author = "Andrea Scaglioni"
11+
# Keep in sync with pyproject.toml
12+
release = "0.1.0"
13+
14+
# -- General configuration ---------------------------------------------------
15+
extensions = [
16+
"sphinx.ext.autodoc",
17+
"sphinx.ext.napoleon",
18+
"sphinx.ext.viewcode",
19+
"sphinx.ext.autosummary",
20+
"sphinx_autodoc_typehints",
21+
"sphinx_mdinclude",
22+
"sphinx_copybutton",
23+
]
24+
25+
autosummary_generate = True
26+
templates_path = ["_templates"]
27+
exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
28+
29+
# -- Options for HTML output -------------------------------------------------
30+
html_theme = "pydata_sphinx_theme"
31+
html_static_path = ["_static"]
32+
33+
# Autodoc settings
34+
autodoc_default_options = {
35+
"members": True,
36+
"undoc-members": False,
37+
"show-inheritance": True,
38+
}
39+
40+
autodoc_typehints = "description"
41+
42+
# Optional: link to other projects
43+
intersphinx_mapping = {
44+
"python": ("https://docs.python.org/3", None),
45+
}

‎docs/index.rst‎

Lines changed: 156 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,156 @@
1+
python-project-template Documentation
2+
=====================================
3+
4+
**python-project-template is a minimal Python project aimed at demonstrating good coding practices.**
5+
6+
The library provides a small dependence-free Calculator API (Operation, OperationRegistry, Calculator) that can register and compose simple mathematical operations.
7+
This simple code is used to showcase some good coding practices:
8+
9+
- Argument validation with type annotation and checking with the ``typing`` module
10+
- Consistent error messages for invalid operations and inputs through custom ``Exceptions``
11+
- Unit tests unit with ``pytest``. Use of :file:`tests/convtest.py` to set global testing variables
12+
- Example notebooks and scripts
13+
- Google-style documentation with ``sphinx``
14+
- Pre-commit routine set up in file :file:`.pre-commit-config.yaml`. It includes:
15+
16+
- Formatting with ``black``
17+
- Linting with ``ruff-pre-commit``
18+
- Type checking with ``mypy``
19+
- Additional checks and fixes (remove trailing white spaces, ensure one empty line at end of the file, YAML files syntax check, prevent committing large files) with ``pre-commit-hooks``
20+
21+
- Modern packaging, easy installation, and project settings with ``pyproject.toml``
22+
- Automated test suite and coverage reporting integrated with `GitHub Actions`; coverage reports can be published to `GitHub Pages`. Setup through file :file:`.github/workflows/tests.yml`
23+
- Automatic compilation and deployment of the documentation to `GitHub Pages` with `Github-Actions`. Setup through file :file:`.github/workflows/docs.yml` [TODO]
24+
- Easy contribution workflow.
25+
26+
27+
Installation
28+
------------
29+
30+
Clone the repository, create a virtual environment (recommended), and install dependencies and editable installation of ``python-project-template``:
31+
32+
.. code-block:: bash
33+
34+
git clone <repo-url>
35+
cd python-project-template
36+
python3 -m venv .venv
37+
source .venv/bin/activate
38+
python -m pip install --upgrade pip setuptools wheel
39+
pip install -e ".[dev]"
40+
41+
Quick usage
42+
-----------
43+
44+
The following is a quick example for the Calculator API.
45+
46+
.. code-block:: python
47+
48+
from python_project_template import default_calculator, Operation
49+
50+
calc = default_calculator()
51+
print(calc.apply('add', 2, 3)) # -> 5
52+
53+
f = calc.compose(['neg', 'sqr'])
54+
print(f(3)) # -> 9
55+
56+
def inc(x):
57+
return x + 1
58+
59+
calc.register(Operation('inc', inc, arity=1), replace=True)
60+
print(calc.apply('inc', 4))
61+
62+
63+
Find additional example in:
64+
65+
- ``experiments/`` — short runnable demos
66+
- ``notebooks/`` — exploratory notebooks
67+
68+
69+
API reference
70+
-------------
71+
72+
See the full API reference for module and class details:
73+
:doc:`API reference <api>`
74+
75+
Running tests
76+
-------------
77+
78+
Run the full test suite with coverage:
79+
80+
.. code-block:: bash
81+
82+
pytest -q --cov=python_project_template --cov-report=term --cov-report=html
83+
84+
Open ``htmlcov/index.html`` to view the coverage report.
85+
86+
87+
Project structure
88+
-----------------
89+
90+
The project presents the following directory structure:
91+
::
92+
93+
src/python_project_template/ # Core library package
94+
calculator.py # Calculator API
95+
operations.py # Built-in operations
96+
registry.py # Operation registry
97+
exceptions.py # Custom error types
98+
utils.py # Utility functions
99+
experiments/ # Example scripts
100+
notebooks/ # Jupyter notebooks
101+
tests/ # Test suite
102+
docs/ # Documentation
103+
.github/
104+
workflows/
105+
tests.yml # GitHub Actions workflow for automated testing and coverage reporting
106+
docs.yml # GitHub Actions workflow for automated documentation and deployment
107+
pyproject.toml # Build/config file
108+
README.md # Project overview
109+
LICENSE # License info
110+
CITATION.cff # Citation metadata
111+
112+
113+
Contributing
114+
------------
115+
116+
A quick workflow:
117+
118+
.. code-block:: bash
119+
120+
git checkout -b feat/your-feature
121+
# make changes
122+
pytest
123+
git add -A && git commit -m "Add feature"
124+
git push --set-upstream origin feat/your-feature
125+
126+
Use ``pip install -e .[dev]`` to get dev tools (pre-commit, black, ruff, mypy)
127+
and run ``pre-commit run --all-files`` before committing.
128+
129+
130+
License
131+
-------
132+
133+
This project is licensed under the MIT License — see the ``LICENSE`` file.
134+
135+
136+
Questions
137+
---------
138+
139+
If you have questions or want help extending the project (docs, CI, or examples),
140+
open an issue or drop a message in the repository.
141+
142+
143+
.. toctree::
144+
.. :maxdepth: 2
145+
.. :caption: Contents:
146+
147+
.. usage
148+
.. api
149+
150+
151+
Indices and tables
152+
==================
153+
154+
* :ref:`genindex`
155+
* :ref:`modindex`
156+
* :ref:`search`

‎docs/requirements.txt‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
# This file exists for tools (or CI) that expect a requirements.txt for docs.
2+
#
3+
# Preferred: install the docs extras defined in `pyproject.toml` so you only
4+
# have one source of truth for development and documentation dependencies:
5+
#
6+
# pip install -e ".[docs]"
7+
#
8+
# Or include docs in your editable dev install:
9+
#
10+
# pip install -e ".[dev,docs]"
11+
#
12+
# If you still need a plain requirements file (for ReadTheDocs or similar),
13+
# keep the minimal fallback below or generate a pinned list from pyproject.
14+
15+
sphinx>=7.0
16+
pydata-sphinx-theme
17+
sphinx-autodoc-typehints

‎pyproject.toml‎

Lines changed: 8 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -41,9 +41,14 @@ dev = [
4141
]
4242

4343
docs = [
44-
"sphinx>=7.0",
45-
"pydata-sphinx-theme",
46-
"sphinx-autodoc-typehints",
44+
"sphinx.ext.autodoc",
45+
"sphinx.ext.napoleon",
46+
"sphinx.ext.viewcode",
47+
"sphinx.ext.autosummary",
48+
"sphinx_autodoc_typehints",
49+
'sphinx-mdinclude',
50+
"sphinx_rtd_theme",
51+
"sphinx-copybutton"
4752
]
4853

4954

0 commit comments

Comments
 (0)