Skip to content

Commit 031f378

Browse files
GutsGuts
authored
Merge pull request #52 from WhereGroup/docs/integrate-contributing-guidelines-and-changelog
Documentation: complete contributing guide and publish to GitHub Pages using GitHub Actions
2 parents 64b57cb + 69d6391 commit 031f378

File tree

12 files changed

+383
-1
lines changed

12 files changed

+383
-1
lines changed

‎.github/workflows/documentation.yml‎

Lines changed: 105 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,105 @@
1+
name: "📚 Documentation"
2+
3+
on:
4+
push:
5+
branches:
6+
- main
7+
paths:
8+
- ".github/workflows/documentation.yml"
9+
- "docs/*/**"
10+
- "profile_manager/**/*.py"
11+
- "profile_manager/metadata.txt"
12+
- "requirements/documentation.txt"
13+
tags:
14+
- "*"
15+
16+
pull_request:
17+
branches:
18+
- main
19+
paths:
20+
- ".github/workflows/documentation.yml"
21+
- docs/**/*
22+
- requirements/documentation.txt
23+
24+
workflow_dispatch:
25+
26+
workflow_run:
27+
workflows:
28+
- "Packager 📦"
29+
types:
30+
- completed
31+
32+
# Allow one concurrent deployment per branch/pr
33+
concurrency:
34+
group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
35+
cancel-in-progress: true
36+
37+
env:
38+
PROJECT_FOLDER: "profile_manager"
39+
PYTHON_VERSION: 3.9
40+
41+
# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
42+
permissions:
43+
contents: read
44+
pages: write
45+
id-token: write
46+
47+
jobs:
48+
build:
49+
runs-on: ubuntu-latest
50+
51+
steps:
52+
- name: Get source code
53+
uses: actions/checkout@v4
54+
55+
- name: Set up Python
56+
uses: actions/setup-python@v5
57+
with:
58+
cache: "pip"
59+
cache-dependency-path: "requirements/documentation.txt"
60+
python-version: ${{ env.PYTHON_VERSION }}
61+
62+
- name: Install dependencies
63+
run: |
64+
python -m pip install --upgrade pip setuptools wheel
65+
python -m pip install -U -r requirements/documentation.txt
66+
67+
- name: Build doc using Sphinx
68+
run: sphinx-build -b html -d docs/_build/cache -j auto docs docs/_build/html
69+
70+
- name: Save build doc as artifact
71+
uses: actions/upload-artifact@v4
72+
with:
73+
name: documentation
74+
path: docs/_build/html/*
75+
if-no-files-found: error
76+
retention-days: 30
77+
78+
- name: Download artifact from build workflow
79+
if: github.event_name == 'push' && (startsWith(github.ref, 'refs/tags/') || github.ref == 'refs/heads/main')
80+
uses: dawidd6/action-download-artifact@19f6be5f04a702e84928b9c7db33da57bd5415c2
81+
with:
82+
allow_forks: false
83+
branch: main
84+
event: push
85+
github_token: ${{ secrets.GITHUB_TOKEN }}
86+
if_no_artifact_found: warn
87+
name: ${{ env.PROJECT_FOLDER }}-latest
88+
path: docs/_build/html/
89+
# run_id: ${{ github.event.workflow_run.id }}
90+
workflow: package_and_release.yml
91+
92+
- name: Setup Pages
93+
uses: actions/configure-pages@v5
94+
if: github.event_name == 'push' && (startsWith(github.ref, 'refs/tags/') || github.ref == 'refs/heads/main')
95+
96+
- name: Upload artifact
97+
uses: actions/upload-pages-artifact@v3
98+
if: github.event_name == 'push' && (startsWith(github.ref, 'refs/tags/') || github.ref == 'refs/heads/main')
99+
with:
100+
path: docs/_build/html/
101+
102+
- name: Deploy to GitHub Pages
103+
id: deployment
104+
if: github.event_name == 'push' && (startsWith(github.ref, 'refs/tags/') || github.ref == 'refs/heads/main')
105+
uses: actions/deploy-pages@v4

‎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 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.

0 commit comments

Comments
 (0)