Skip to content

Commit 760ac72

Browse files
andreascaglioniandreascaglioni
committed
added documentation
1 parent 34a0921 commit 760ac72

File tree

18 files changed

+350
-151
lines changed

18 files changed

+350
-151
lines changed

‎.github/workflows/deploy-docs.yml‎

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
1+
name: "docs: build and deploy"
2+
3+
on:
4+
push:
5+
branches:
6+
- main
7+
workflow_dispatch: {}
8+
9+
concurrency:
10+
group: ${{ github.workflow }}-${{ github.ref }}
11+
cancel-in-progress: true
12+
13+
jobs:
14+
build-and-deploy:
15+
name: Build and publish Sphinx docs to GitHub Pages
16+
runs-on: ubuntu-latest
17+
18+
steps:
19+
- name: Checkout
20+
uses: actions/checkout@v4
21+
22+
- name: Set up Python
23+
uses: actions/setup-python@v5
24+
with:
25+
python-version: '3.11'
26+
cache: 'pip'
27+
28+
- name: Install dependencies
29+
run: |
30+
python -m pip install --upgrade pip
31+
# install project and docs extras defined in pyproject.toml
32+
pip install -e ".[docs]"
33+
34+
- name: Build Sphinx HTML
35+
working-directory: docs
36+
run: |
37+
sphinx-build -b html -a -E -W -T . _build/html
38+
39+
- name: Upload pages artifact
40+
uses: actions/upload-pages-artifact@v1
41+
with:
42+
path: docs/_build/html
43+
44+
deploy-pages:
45+
name: Deploy to GitHub Pages
46+
needs: build-and-deploy
47+
runs-on: ubuntu-latest
48+
permissions:
49+
pages: write
50+
id-token: write
51+
52+
steps:
53+
- name: Deploy to GitHub Pages
54+
uses: actions/deploy-pages@v1

‎README.md‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -32,7 +32,7 @@ This simple code is used to showcase some good coding practices.
3232
- Type checking with ``mypy``
3333
- Additional checks and fixes (trailing whitespace removal, enforcing empty line at EOF, YAML syntax checks, blocking large files) via ``pre-commit-hooks``
3434

35-
- **Modern packaging** and easy installation using ``pyproject.toml``.
35+
-- **Modern packaging** and easy installation using :file:`pyproject.toml`.
3636
- **Automated test suite and coverage reporting** integrated with GitHub Actions; coverage reports can be published to GitHub Pages. Setup in :file:`.github/workflows/tests.yml`.
3737
- **Automatic documentation deployment** to GitHub Pages with GitHub Actions. Setup in :file:`.github/workflows/docs.yml` [TODO].
3838
- **Easy contribution workflow** for new features and improvements.
@@ -86,6 +86,8 @@ print(calc.apply('inc', 4)) # -> 5
8686

8787
For detailed documentation, please visit our [GitHub Pages](https://andreascaglioni.github.io/your-repo-name/).
8888

89+
If you want to build and deploy the docs yourself via GitHub Actions, see `docs/README_DOCS_DEPLOY.md` for configuration and setup steps.
90+
8991
## Running tests
9092

9193
Run the full test suite with coverage:

‎docs/Makefile‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,10 +2,13 @@ SPHINXBUILD = sphinx-build
22
SOURCEDIR = .
33
BUILDDIR = _build
44

5-
.PHONY: html clean
5+
.PHONY: html clean spelling
66

77
html:
88
$(SPHINXBUILD) -M html "$(SOURCEDIR)" "$(BUILDDIR)"
99

10+
spelling:
11+
$(SPHINXBUILD) -b spelling "$(SOURCEDIR)" "$(BUILDDIR)"
12+
1013
clean:
1114
rm -rf "$(BUILDDIR)"

‎docs/_static/logo.svg‎

Lines changed: 4 additions & 0 deletions
Loading

‎docs/appendix.rst‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
Appendix
2+
========
3+
4+
Contributing
5+
------------
6+
7+
A quick workflow:
8+
9+
.. code-block:: bash
10+
11+
git checkout -b feat/your-feature
12+
# make changes
13+
pytest
14+
git add -A && git commit -m "Add feature"
15+
git push --set-upstream origin feat/your-feature
16+
17+
Use ``pip install -e .[dev]`` to get development tools (pre-commit, black, ruff, mypy)
18+
and run ``pre-commit run --all-files`` before committing.
19+
20+
21+
License
22+
-------
23+
24+
This project is licensed under the MIT License — see the ``LICENSE`` file.
25+
26+
27+
Questions
28+
---------
29+
30+
If you have questions or want help extending the project (docs, CI, or examples),
31+
open an issue or create a discussion in the repository.

‎docs/conf.py‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,7 @@
2020
"sphinx_autodoc_typehints",
2121
"sphinx_mdinclude",
2222
"sphinx_copybutton",
23+
"sphinxcontrib.spelling",
2324
]
2425

2526
autosummary_generate = True
@@ -30,6 +31,14 @@
3031
html_theme = "pydata_sphinx_theme"
3132
html_static_path = ["_static"]
3233

34+
# Use the docs static logo now stored in docs/_static
35+
html_logo = "_static/logo.svg"
36+
37+
# Set a concise HTML title (avoid theme/appending 'Documentation')
38+
html_title = "python-project-template"
39+
# Optional short title used in smaller viewports or sidebars
40+
html_short_title = "py-project-template"
41+
3342
# Autodoc settings
3443
autodoc_default_options = {
3544
"members": True,
@@ -43,3 +52,8 @@
4352
intersphinx_mapping = {
4453
"python": ("https://docs.python.org/3", None),
4554
}
55+
56+
# Spelling check options
57+
spelling_lang = "en_US"
58+
spelling_word_list_filename = "spelling_wordlist.txt"
59+
spelling_show_suggestions = True

‎docs/docs_github.rst‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
Documentation (GitHub Actions)
2+
==============================
3+
4+
This page explains how the repository builds the Sphinx documentation and publishes
5+
the generated HTML to GitHub Pages using GitHub Actions.
6+
7+
The workflow does the following:
8+
9+
- Whenever a commit is pushed to `main`, the workflow checks out the repository (manual dispatch is also supported).
10+
- Sets up Python and installs the ``docs`` dependencies from :file:`pyproject.toml`.
11+
- Builds HTML with ``sphinx-build`` into ``docs/_build/html``.
12+
- Uploads the built HTML as a Pages artifact and deploys it to GitHub Pages.
13+
14+
Repository setup (one-time)
15+
---------------------------
16+
1. Ensure the repository has GitHub Pages enabled for the ``gh-pages`` site (no manual branch required when using the Pages actions). In repository Settings → Pages you should see the site status after the first successful run.
17+
2. No secret is required. The workflow uses the repository's built-in ``GITHUB_TOKEN`` permissions to publish pages.
18+
19+
Local testing
20+
-------------
21+
To build the docs locally (recommended before pushing):
22+
23+
.. code-block:: bash
24+
25+
# create and activate a venv
26+
python -m venv .venv
27+
source .venv/bin/activate
28+
python -m pip install --upgrade pip
29+
# install docs dependencies
30+
pip install -e ".[docs]"
31+
# build
32+
cd docs
33+
sphinx-build -b html -a -E -W -T . _build/html
34+
35+
Autosummary and generated files
36+
-------------------------------
37+
- ``autosummary_generate = True`` is enabled in ``docs/conf.py``, so Sphinx will generate the ``_autosummary`` pages during the build.
38+
- Best practice: do NOT commit generated files (``docs/_build``, ``docs/_autosummary``) to the repository. Keep them in ``.gitignore`` and let CI produce the HTML. If you plan to serve source HTML directly from the ``docs/`` folder (without a build step), then you'd need to commit generated files — but the current workflow builds on CI and deploys the result, so committing generated files is unnecessary.
39+
40+
Troubleshooting
41+
---------------
42+
- If builds fail due to missing packages, ensure :file:`pyproject.toml` contains the correct ``docs`` extras and that ``pip install -e ".[docs]"`` succeeds.
43+
- If the site does not appear after the workflow succeeds, check Settings → Pages to ensure the site is not blocked by organization policy.
44+
45+
That's it — the workflow will publish your Sphinx docs automatically when you push to ``main``.

‎docs/docs_local.rst‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
Documentation (local)
2+
=====================
3+
4+
Good documentation is essential for code sustainability. It ensures that others can understand, use, and maintain the project, especially if the original developer leaves. Adopting a consistent style, such as Google (used here) or NumPy, helps keep docs clear and accessible.
5+
6+
To build the documentation for this project, follow these steps:
7+
8+
1. Ensure all dependencies for documentation generation are installed, for example with ``pip install -e ".[docs]"``.
9+
2. Run the documentation build command (for example, ``make html``).
10+
3. Review the generated HTML in ``docs/_build/html``.

‎docs/features.rst‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
Features
2+
========
3+
4+
This code is used to showcase a number of good software practices:
5+
6+
- Argument validation with type annotations and runtime checking using the ``typing`` module
7+
- Consistent error messages for invalid operations and inputs via custom ``Exceptions``
8+
- Unit tests with ``pytest``. Use :file:`tests/convtest.py` to set global testing variables
9+
- Example notebooks and scripts
10+
- Google-style documentation with ``sphinx``
11+
- Pre-commit routine set up in file :file:`.pre-commit-config.yaml`. It includes:
12+
13+
- Formatting with ``black``
14+
- Linting with ``ruff`` via pre-commit
15+
- Type checking with ``mypy``
16+
- Additional checks and fixes (remove trailing whitespace, ensure one empty line at end of file, YAML syntax checks, prevent committing large files) with ``pre-commit-hooks``
17+
18+
- Modern packaging, easy installation, and project settings with :file:`pyproject.toml`
19+
- Automated test suite and coverage reporting integrated with `GitHub Actions`; coverage reports can be published to `GitHub Pages`. See :file:`.github/workflows/tests.yml`
20+
- Automatic build and deployment of the documentation to `GitHub Pages` with GitHub Actions. See :file:`.github/workflows/docs.yml`
21+
- Easy contribution workflow.

‎docs/index.rst‎

Lines changed: 14 additions & 141 deletions
Original file line numberDiff line numberDiff line change
@@ -3,149 +3,22 @@ python-project-template Documentation
33

44
**python-project-template is a minimal Python project aimed at demonstrating good coding practices.**
55

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-
6+
The library provides a small dependency-free Calculator API (Operation, OperationRegistry, Calculator) that can register and compose simple mathematical operations.
7+
This code is used to showcase a number of good software practices. See the next page for a detailed list.
1428

1439
.. toctree::
144-
.. :maxdepth: 2
145-
.. :caption: Contents:
146-
147-
.. usage
148-
.. api
10+
:maxdepth: 2
11+
:caption: Contents:
12+
13+
features
14+
installation
15+
tests
16+
usage
17+
docs_local
18+
docs_github
19+
structure
20+
api
21+
appendix
14922

15023

15124
Indices and tables

0 commit comments

Comments
 (0)