Skip to content

Commit e077a29

Browse files
GutsGuts
committed
add(docs): complete contributing guide and generate documentation with Sphinx
1 parent daf21c6 commit e077a29

File tree

10 files changed

+277
-0
lines changed

10 files changed

+277
-0
lines changed

‎docs/conf.py‎

Lines changed: 144 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,144 @@
1+
#!python3
2+
3+
"""
4+
Configuration for project documentation using Sphinx.
5+
"""
6+
7+
# standard
8+
import sys
9+
from datetime import datetime
10+
from os import environ, path
11+
12+
sys.path.insert(0, path.abspath("..")) # move into project package
13+
14+
# Package
15+
from profile_manager import __about__
16+
17+
# -- Project information -----------------------------------------------------
18+
author = __about__.__author__
19+
copyright = __about__.__copyright__
20+
description = __about__.__summary__
21+
project = __about__.__title__
22+
version = release = __about__.__version__
23+
24+
# -- General configuration ---------------------------------------------------
25+
26+
# Add any Sphinx extension module names here, as strings. They can be
27+
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
28+
# ones.
29+
extensions = [
30+
# Sphinx included
31+
"sphinx.ext.autodoc",
32+
"sphinx.ext.autosectionlabel",
33+
"sphinx.ext.extlinks",
34+
"sphinx.ext.githubpages",
35+
"sphinx.ext.intersphinx",
36+
"sphinx.ext.viewcode",
37+
# 3rd party
38+
"myst_parser",
39+
"sphinx_copybutton",
40+
]
41+
42+
43+
# The suffix(es) of source filenames.
44+
# You can specify multiple suffix as a list of string:
45+
source_suffix = {".md": "markdown", ".rst": "restructuredtext"}
46+
autosectionlabel_prefix_document = True
47+
# The master toctree document.
48+
master_doc = "index"
49+
50+
51+
# List of patterns, relative to source directory, that match files and
52+
# directories to ignore when looking for source files.
53+
# This pattern also affects html_static_path and html_extra_path .
54+
exclude_patterns = [
55+
"_build",
56+
".venv",
57+
"Thumbs.db",
58+
".DS_Store",
59+
"_output",
60+
"ext_libs",
61+
"tests",
62+
"demo",
63+
]
64+
65+
# The name of the Pygments (syntax highlighting) style to use.
66+
pygments_style = "sphinx"
67+
68+
69+
# -- Options for HTML output -------------------------------------------------
70+
71+
# -- Theme
72+
73+
html_favicon = str(__about__.__icon_path__)
74+
html_logo = str(__about__.__icon_path__)
75+
# uncomment next line if you store some statics which are not directly linked into the markdown/RST files
76+
# html_static_path = ["static/include_additional"]
77+
html_theme = "furo"
78+
79+
# -- EXTENSIONS --------------------------------------------------------
80+
81+
# Sphinx API doc
82+
autodoc_mock_imports = [
83+
"qgis.core",
84+
"qgis.gui",
85+
"qgis.PyQt",
86+
"qgis.PyQt.QtCore",
87+
"qgis.PyQt.QtGui",
88+
"qgis.PyQt.QtNetwork",
89+
"qgis.PyQt.QtWidgets",
90+
"qgis.utils",
91+
]
92+
93+
# Configuration for intersphinx (refer to others docs).
94+
intersphinx_mapping = {
95+
"PyQt5": ("https://www.riverbankcomputing.com/static/Docs/PyQt5", None),
96+
"python": ("https://docs.python.org/3/", None),
97+
"qgis": ("https://qgis.org/pyqgis/master/", None),
98+
}
99+
100+
# MyST Parser
101+
myst_enable_extensions = [
102+
"colon_fence",
103+
"deflist",
104+
"dollarmath",
105+
"html_image",
106+
"linkify",
107+
"replacements",
108+
"smartquotes",
109+
"substitution",
110+
]
111+
112+
myst_substitutions = {
113+
"author": author,
114+
"date_update": datetime.now().strftime("%d %B %Y"),
115+
"description": description,
116+
"qgis_version_max": __about__.__plugin_md__.get("general").get(
117+
"qgismaximumversion"
118+
),
119+
"qgis_version_min": __about__.__plugin_md__.get("general").get(
120+
"qgisminimumversion"
121+
),
122+
"repo_url": __about__.__uri__,
123+
"title": project,
124+
"version": version,
125+
}
126+
127+
myst_url_schemes = ("http", "https", "mailto")
128+
129+
130+
# -- API Doc --------------------------------------------------------
131+
# run api doc
132+
def run_apidoc(_):
133+
from sphinx.ext.apidoc import main
134+
135+
cur_dir = path.normpath(path.dirname(__file__))
136+
output_path = path.join(cur_dir, "_apidoc")
137+
modules = path.normpath(path.join(cur_dir, "../profile_manager"))
138+
exclusions = ["../.venv", "../tests"]
139+
main(["-e", "-f", "-M", "-o", output_path, modules] + exclusions)
140+
141+
142+
# launch setup
143+
def setup(app):
144+
app.connect("builder-inited", run_apidoc)

‎docs/development/contribute.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
```{include} ../../CONTRIBUTING.md
2+
```

‎docs/development/documentation.md‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
# Documentation
2+
3+
Project uses Sphinx to generate documentation from docstrings (documentation in-code) and custom pages written in Markdown (through the [MyST parser](https://myst-parser.readthedocs.io/en/latest/)).
4+
5+
## Build documentation website
6+
7+
To build it:
8+
9+
```bash
10+
# install aditionnal dependencies
11+
python -m pip install -U -r requirements/documentation.txt
12+
# build it
13+
sphinx-build -b html -d docs/_build/cache -j auto -q docs docs/_build/html
14+
```
15+
16+
Open `docs/_build/index.html` in a web browser.
17+
18+
## Write documentation using live render
19+
20+
```bash
21+
sphinx-autobuild -b html docs/ docs/_build
22+
```
23+
24+
Open <http://localhost:8000> in a web browser to see the HTML render updated when a file is saved.

‎docs/development/environment.md‎

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
# Development
2+
3+
## Environment setup
4+
5+
> Typically on Ubuntu (but should work on Windows).
6+
7+
### 1. Install virtual environment
8+
9+
Using [qgis-venv-creator](https://github.com/GispoCoding/qgis-venv-creator) (see [this article](https://blog.geotribu.net/2024/11/25/creating-a-python-virtual-environment-for-pyqgis-development-with-vs-code-on-windows/#with-the-qgis-venv-creator-utility)) through [pipx](https://pipx.pypa.io) (`sudo apt install pipx`):
10+
11+
```sh
12+
pipx run qgis-venv-creator
13+
```
14+
15+
Old school way:
16+
17+
```bash
18+
# create virtual environment linking to system packages (for pyqgis)
19+
python3 -m venv .venv --system-site-packages
20+
source .venv/bin/activate
21+
```
22+
23+
### 2. Install development dependencies
24+
25+
```sh
26+
# bump dependencies inside venv
27+
python -m pip install -U pip
28+
python -m pip install -U -r requirements/development.txt
29+
30+
# install git hooks (pre-commit)
31+
pre-commit install
32+
```
33+
34+
### Dedicated QGIS profile
35+
36+
It's recommended to create a dedicated QGIS profile for the development of the plugin to avoid conflicts with other plugins.
37+
38+
1. From the command-line (a terminal with or OSGeo4W Shell):
39+
40+
```sh
41+
# Linux
42+
qgis --profile plg_profile_manager
43+
# Windows - OSGeo4W Shell
44+
qgis-ltr --profile plg_profile_manager
45+
# Windows - PowerShell opened in the QGIS installation directory
46+
PS C:\Program Files\QGIS 3.40.4\LTR\bin> .\qgis-ltr-bin.exe --profile plg_profile_manager
47+
```
48+
49+
1. Then, set the `QGIS_PLUGINPATH` environment variable to the path of the plugin in profile preferences:
50+
51+
![QGIS - Add QGIS_PLUGINPATH environment variable in profile settings](../static/dev_qgis_set_pluginpath_envvar.png)
52+
53+
1. Finally, enable the plugin in the plugin manager (ignore invalid folders like documentation, tests, etc.):
54+
55+
![QGIS - Enable the plugin in the plugin manager](../static/dev_qgis_enable_plugin.png)

‎docs/development/history.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
```{include} ../../CHANGELOG.md
2+
```

‎docs/index.md‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
# {{ title }} - Documentation
2+
3+
> **Description:** {{ description }}
4+
> **Author and contributors:** {{ author }}
5+
> **Plugin version:** {{ version }}
6+
> **QGIS minimum version:** {{ qgis_version_min }}
7+
> **QGIS maximum version:** {{ qgis_version_max }}
8+
> **Source code:** {{ repo_url }}
9+
> **Last documentation update:** {{ date_update }}
10+
11+
----
12+
13+
```{toctree}
14+
---
15+
caption: Usage
16+
maxdepth: 1
17+
---
18+
usage/installation
19+
```
20+
21+
```{toctree}
22+
---
23+
caption: Contribution guide
24+
maxdepth: 1
25+
---
26+
development/contribute
27+
development/environment
28+
development/documentation
29+
development/translation
30+
development/packaging
31+
development/history
32+
Code documentation <_apidoc/modules>
33+
```

‎docs/static/dev_qgis_enable_plugin.png‎

46.1 KB
Loading

‎docs/static/dev_qgis_set_pluginpath_envvar.png‎

36.6 KB
Loading

‎docs/usage/installation.md‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
# Installation
2+
3+
## Stable version (recomended)
4+
5+
This plugin is published on the official QGIS plugins repository: <https://plugins.qgis.org/plugins/profile_manager/>.
6+
7+
## Beta versions released
8+
9+
Enable experimental extensions in the QGIS plugins manager settings panel.

‎requirements/documentation.txt‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
# Documentation (for devs)
2+
# -----------------------
3+
4+
furo>=2024
5+
myst-parser[linkify]>=2
6+
sphinx-autobuild>=2024
7+
sphinx-copybutton>=0.5,<1
8+
sphinxext-opengraph>=0.4,<1

0 commit comments

Comments
 (0)