Skip to content

Commit 9e4d9e7

Browse files
TeschlTeschl
authored
Add Sphinx docs generation (#33)
This adds a basic framework for documentation using Sphinx. API documentation is automatically generated from the Python docstrings. A GitHub Actions workflow builds the documentation and pushes it to the repository's GitHub Pages site.
1 parent 3eb8997 commit 9e4d9e7

17 files changed

+363
-19
lines changed

‎.github/workflows/docs.yaml

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
name: docs
2+
3+
on:
4+
push:
5+
branches: ["main"]
6+
7+
jobs:
8+
build:
9+
runs-on: ubuntu-latest
10+
steps:
11+
- name: Checkout
12+
uses: actions/checkout@v4
13+
14+
- name: Install Pandoc
15+
run: sudo apt-get install -y pandoc
16+
17+
- name: Install Python build dependencies
18+
run: |
19+
python -m pip install --upgrade pip
20+
pip install -r ${{ github.workspace }}/docs/requirements.txt
21+
python3 -m pip install .[opensimplex]
22+
23+
- name: Build Sphinx documentation
24+
working-directory: ${{ github.workspace }}/docs
25+
run: |
26+
make clean
27+
make html
28+
29+
- name: Package artifact
30+
uses: actions/upload-pages-artifact@v3
31+
with:
32+
path: ${{ github.workspace }}/docs/_build/html
33+
34+
deploy:
35+
needs: build
36+
permissions:
37+
pages: write
38+
id-token: write
39+
40+
environment:
41+
name: github-pages
42+
url: ${{ steps.deployment.outputs.page_url }}
43+
runs-on: ubuntu-latest
44+
steps:
45+
- name: Deploy to GitHub Pages
46+
id: deployment
47+
uses: actions/deploy-pages@v4

‎.gitignore

Lines changed: 7 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,14 @@
11
# ignore .vscode settings:
22
.vscode/
33

4-
# ignore example directory
5-
examples/perfectworld.tif
6-
74
# ignore dist directory
85
dist/
96

10-
# ignore C++/C library
11-
src/topotoolbox/libtopotoolbox.so
12-
137
# ingnore tests pycache
14-
tests/__pycache__
8+
tests/__pycache__
9+
10+
# ignore build docs
11+
docs/_build/*
12+
13+
# ignore _autosummary
14+
docs/_autosummary/*

‎docs/Makefile

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
# Minimal makefile for Sphinx documentation
2+
#
3+
4+
# You can set these variables from the command line, and also
5+
# from the environment for the first two.
6+
SPHINXOPTS ?=
7+
SPHINXBUILD ?= sphinx-build
8+
SOURCEDIR = .
9+
BUILDDIR = _build
10+
11+
EXAMPLEDIR = ../examples
12+
DOCEXAMPLEDIR = $(SOURCEDIR)/_examples
13+
14+
# Put it first so that "make" without argument is like "make help".
15+
help:
16+
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
17+
18+
.PHONY: help Makefile
19+
20+
# Target to build HTML documentation, including copying/removing examples
21+
html:
22+
@echo "Copying examples directory..."
23+
@cp -r $(EXAMPLEDIR) $(DOCEXAMPLEDIR)
24+
@$(SPHINXBUILD) -M html "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
25+
@echo "Cleaning up examples directory..."
26+
@rm -rf $(DOCEXAMPLEDIR)
27+
28+
# Catch-all target: route all unknown targets to Sphinx using the new
29+
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
30+
%: Makefile
31+
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

‎docs/README.md

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
# Generation Sphinx Documentation
2+
3+
Before being able to generate the Docs, make sure to install all the python dependencies: `pip install -r requirements.txt` and pandoc. However, they can be ignored since they don't lead to any actual issues. To generate the Sphinx documentation HTML page, run the following commands (Linux):
4+
5+
```bash
6+
cd /path/to/topotoolbox/docs/
7+
make clean
8+
make html
9+
```
10+
11+
then open the `pytopotoolbox/docs/_build/html/index.html` file in your browser.

‎docs/api.rst

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
API Documentation
2+
=================
3+
4+
.. autosummary::
5+
:toctree: _autosummary
6+
:recursive:
7+
8+
topotoolbox

‎docs/conf.py

Lines changed: 64 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,64 @@
1+
# Configuration file for the Sphinx documentation builder.
2+
#
3+
# For the full list of built-in configuration values, see the documentation:
4+
# https://www.sphinx-doc.org/en/master/usage/configuration.html
5+
6+
# -- Project information -----------------------------------------------------
7+
# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
8+
9+
import os
10+
import sys
11+
12+
import sphinx_book_theme
13+
14+
import topotoolbox
15+
16+
17+
extensions = [
18+
'sphinx.ext.autodoc',
19+
'sphinx.ext.autosummary',
20+
'sphinx.ext.napoleon',
21+
'sphinx.ext.viewcode',
22+
'sphinx.ext.todo',
23+
'nbsphinx',
24+
]
25+
26+
project = 'TopoToolbox'
27+
copyright = '2024, TopoToolbox Team'
28+
author = 'TopoToolbox Team'
29+
release = '3.0.1'
30+
31+
# -- General configuration ---------------------------------------------------
32+
# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
33+
34+
templates_path = ['_templates']
35+
exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
36+
37+
38+
# -- Options for HTML output -------------------------------------------------
39+
# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
40+
41+
html_theme = 'sphinx_book_theme'
42+
html_static_path = ['_static']
43+
html_logo = 'logo.png'
44+
45+
html_context = {
46+
"default_mode": "light",
47+
}
48+
49+
# -- Options for nbsphinx ----------------------------------------------------
50+
51+
nbsphinx_allow_errors = True
52+
53+
# -- Options for autodoc -----------------------------------------------------
54+
55+
autodoc_default_options = {
56+
'members': True,
57+
'undoc-members': True,
58+
'private-members': False,
59+
'special-members': '__init__',
60+
'inherited-members': True,
61+
'show-inheritance': True,
62+
}
63+
64+
autosummary_generate = True # Enable autosummary to generate stub files

‎docs/examples.rst

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
Examples
2+
========
3+
4+
.. nbgallery::
5+
/_examples/test_genGrid
6+
/_examples/test_GridObject
7+
/_examples/test_load_dem
8+
/_examples/example_magic_funcs

‎docs/index.rst

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
Welcome to TopoToolbox's python documentation!
2+
==============================================
3+
4+
.. toctree::
5+
:maxdepth: 1
6+
:caption: Contents:
7+
8+
Installing <installing>
9+
Tutorial <tutorial>
10+
Examples <examples>
11+
API <api>
12+
13+
14+
15+
Indices and tables
16+
==================
17+
18+
* :ref:`genindex`
19+
* :ref:`modindex`
20+
* :ref:`search`

‎docs/installing.rst

Lines changed: 80 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,80 @@
1+
How to install
2+
==============
3+
4+
Generating/Installing distribution archives
5+
-------------------------------------------
6+
7+
For any operating system, install the following:
8+
9+
- **Python**
10+
- **pip**
11+
- **Git** (only when *building* the package yourself)
12+
13+
Linux
14+
~~~~~
15+
16+
**Installing from .whl file**
17+
18+
Make sure to choose the appropriate file for your OS. For Linux, the file name should contain something like: `linux_x86_64`
19+
20+
.. code-block:: bash
21+
22+
pip install dist_name.whl
23+
24+
**Installing directly from the repository:**
25+
26+
.. code-block:: bash
27+
28+
cd path/to/pytopotoolbox
29+
pip install .
30+
31+
**Generating distribution archives**
32+
33+
.. code-block:: bash
34+
35+
cd path/to/pytopotoolbox
36+
python3 -m pip install --upgrade build
37+
python3 -m build
38+
39+
Windows
40+
~~~~~~~
41+
42+
**Installing from .whl file**
43+
44+
Make sure to choose the appropriate file for your OS. For Windows, the file name should contain something like: `win_amd64`.
45+
46+
.. code-block:: bash
47+
48+
pip install dist_name.whl
49+
50+
**Installing directly from the repository:**
51+
52+
Since there are C/C++ files that need to be compiled in order to build the package, there are a few extra steps to take.
53+
54+
1. Install the `Developer Command Prompt for VS 2022 <https://visualstudio.microsoft.com/downloads/>`_.
55+
- Scroll down to '*All Downloads*'
56+
- Open '*Tools for Visual Studio*'
57+
- Download '*Build Tools for Visual Studio 2022*'
58+
- Install it while including the '*Desktop development with C++*' workload
59+
2. To ensure the compiler is working with 64-bit architecture, that is necessary for python, **open 'x64 Native Tools Command Prompt for VS 2022'** instead of the '*Developer Command Prompt*' that defaults to 32-bit architecture.
60+
3. In the newly opened terminal, run:
61+
62+
.. code-block:: bash
63+
64+
cd path\to\pytopotoolbox
65+
pip install .
66+
67+
**Generating distribution archives**
68+
69+
Open the 'x64 Native Tools Command Prompt for VS 2022' Terminal and run:
70+
71+
.. code-block:: bash
72+
73+
cd path\to\pytopotoolbox
74+
py -m pip install --upgrade build
75+
py -m build
76+
77+
Mac
78+
~~~
79+
80+
*work in progress*

‎docs/logo.png

17.6 KB
Loading

‎docs/make.bat

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
@ECHO OFF
2+
3+
pushd %~dp0
4+
5+
REM Command file for Sphinx documentation
6+
7+
if "%SPHINXBUILD%" == "" (
8+
set SPHINXBUILD=sphinx-build
9+
)
10+
set SOURCEDIR=.
11+
set BUILDDIR=_build
12+
13+
%SPHINXBUILD% >NUL 2>NUL
14+
if errorlevel 9009 (
15+
echo.
16+
echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
17+
echo.installed, then set the SPHINXBUILD environment variable to point
18+
echo.to the full path of the 'sphinx-build' executable. Alternatively you
19+
echo.may add the Sphinx directory to PATH.
20+
echo.
21+
echo.If you don't have Sphinx installed, grab it from
22+
echo.https://www.sphinx-doc.org/
23+
exit /b 1
24+
)
25+
26+
if "%1" == "" goto help
27+
28+
%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
29+
goto end
30+
31+
:help
32+
%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
33+
34+
:end
35+
popd

‎docs/requirements.txt

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
Sphinx==7.3.7
2+
sphinx-book-theme==1.1.2
3+
nbsphinx==0.9.4
4+
notebook==7.0.5
5+
jupyter==1.0.0

‎docs/tutorial.rst

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
Tutorial
2+
========
3+
4+
Introduction
5+
------------
6+
7+
Installing
8+
----------
9+
10+
First steps
11+
-----------
12+
13+
Using the provided examples
14+
---------------------------
15+
16+
Using API documentation
17+
-----------------------
18+

‎examples/example_magic_funcs.ipynb

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,12 @@
11
{
22
"cells": [
3+
{
4+
"cell_type": "markdown",
5+
"metadata": {},
6+
"source": [
7+
"## example magic functions"
8+
]
9+
},
310
{
411
"cell_type": "code",
512
"execution_count": null,

‎examples/test_GridObject.ipynb

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,12 @@
11
{
22
"cells": [
3+
{
4+
"cell_type": "markdown",
5+
"metadata": {},
6+
"source": [
7+
"## test GridObject"
8+
]
9+
},
310
{
411
"cell_type": "code",
512
"execution_count": null,

0 commit comments

Comments
 (0)