Skip to content

Commit a8ea9b9

Browse files
📚 docs: create GitHub Pages
- Use `sphinx-book-theme`. - Pin `sphinx` dependencies. See: astropy/astropy#11725
1 parent 81e0d14 commit a8ea9b9

12 files changed

Lines changed: 278 additions & 188 deletions

File tree

‎.github/workflows/docs.yml‎

Lines changed: 82 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,82 @@
1+
name: Documentation
2+
3+
on:
4+
workflow_dispatch:
5+
6+
# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
7+
permissions:
8+
contents: write
9+
pages: write
10+
id-token: write
11+
12+
concurrency:
13+
group: ${{ github.workflow }}-${{ github.ref }}
14+
cancel-in-progress: true
15+
16+
jobs:
17+
deploy-docs:
18+
runs-on: ubuntu-latest
19+
20+
steps:
21+
- name: Checkout
22+
uses: actions/checkout@v3
23+
with:
24+
token: ${{ secrets.PERSONAL_ACCESS_TOKEN }}
25+
fetch-depth: 0
26+
27+
- name: Install `python` ${{ matrix.python-version }}
28+
uses: actions/setup-python@v4
29+
with:
30+
# See https://github.com/astropy/astropy/issues/11725
31+
python-version: "3.9"
32+
33+
- name: Print `python` Version
34+
id: full-python-version
35+
run: echo ::set-output name=version::$(python -c "import sys; print('-'.join(str(v) for v in sys.version_info))")
36+
37+
- name: Install and Configure Poetry
38+
uses: snok/[email protected]
39+
with:
40+
virtualenvs-create: true
41+
virtualenvs-in-project: true
42+
43+
- name: Print `poetry` Version
44+
run: poetry --version
45+
46+
- name: Setup `python` Cache
47+
uses: actions/cache@v3
48+
id: python-cache
49+
with:
50+
path: .venv
51+
key: venv-${{ runner.os }}-${{ steps.full-python-version.outputs.version }}-${{ hashFiles('**/poetry.lock') }}
52+
53+
- name: Verify `python` Cache is Healthy
54+
if: steps.python-cache.outputs.cache-hit == 'true'
55+
run: |
56+
# `timeout` is not available on macOS, so we define a custom function.
57+
[ "$(command -v timeout)" ] || function timeout() { perl -e 'alarm shift; exec @ARGV' "$@"; }
58+
# Using `timeout` is a safeguard against the Poetry command hanging for some reason.
59+
timeout 10s poetry run pip --version || rm -rf .venv
60+
61+
- name: Install Dependencies
62+
if: steps.python-cache.outputs.cache-hit != 'true'
63+
run: |
64+
poetry run python -m pip install --upgrade pip
65+
poetry install
66+
poetry run python -m pip install tox-gh-actions
67+
poetry run python -m pip install pytest-github-actions-annotate-failures
68+
69+
- name: Build Docs
70+
run: |
71+
poetry run make -C docs html
72+
73+
- name: Deploy to GitHub Pages
74+
uses: peaceiris/actions-gh-pages@v3
75+
if: ${{ github.ref == 'refs/heads/main' }}
76+
with:
77+
github_token: ${{ secrets.GITHUB_TOKEN }}
78+
publish_branch: gh-pages
79+
publish_dir: docs/_build/html/
80+
user_name: "github-actions[bot]"
81+
user_email: "github-actions[bot]@users.noreply.github.com"
82+
full_commit_message: ${{ github.event.head_commit.message }}

‎.gitignore‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -68,7 +68,9 @@ instance/
6868
.scrapy
6969

7070
# Sphinx documentation
71+
docs/build
7172
docs/_build/
73+
docs/source/_build
7274
docs/source/doctrees
7375
docs/source/html
7476

@@ -153,3 +155,6 @@ cython_debug/
153155
# and can be added to the global gitignore or merged into this file. For a more nuclear
154156
# option (not recommended) you can uncomment the following to ignore the entire idea folder.
155157
#.idea/
158+
159+
# Logs
160+
logs/

‎.vscode/settings.json‎

Lines changed: 13 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,10 @@
1414
"editor.wordWrap": "bounded",
1515
"editor.wordWrapColumn": 90
1616
},
17+
"[restructuredtext]": {
18+
"editor.wordWrap": "bounded",
19+
"editor.wordWrapColumn": 90
20+
},
1721
"[python]": {
1822
"editor.codeActionsOnSave": {
1923
"source.organizeImports": true
@@ -29,7 +33,7 @@
2933
90
3034
],
3135
"editor.tabCompletion": "on",
32-
"esbonio.sphinx.buildDir": "${workspaceFolder}\\docs\\build",
36+
"esbonio.sphinx.buildDir": "${workspaceFolder}\\docs\\_build",
3337
"esbonio.sphinx.confDir": "${workspaceFolder}\\docs\\source",
3438
"esbonio.sphinx.forceFullBuild": false,
3539
"explorer.compactFolders": false,
@@ -98,7 +102,15 @@
98102
],
99103
"python.testing.pytestEnabled": true,
100104
"python.testing.pytestPath": "${workspaceFolder}/.venv/Scripts/pytest.exe",
105+
"restructuredtext.linter.disabledLinters": [
106+
"doc8",
107+
"rst-lint"
108+
],
101109
"restructuredtext.linter.rstcheck.executablePath": "${workspaceFolder}/.venv/Scripts/rstcheck.exe",
110+
"restructuredtext.linter.rstcheck.extraArgs": [
111+
"--config",
112+
"pyproject.toml"
113+
],
102114
"runOnSave.commands": [
103115
{
104116
"command": ".venv\\Scripts\\pyupgrade --py38-plus ${file}",

‎docs/Makefile‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,14 +6,17 @@
66
SPHINXOPTS ?=
77
SPHINXBUILD ?= sphinx-build
88
SOURCEDIR = source
9-
BUILDDIR = build
9+
BUILDDIR = _build
1010

1111
# Put it first so that "make" without argument is like "make help".
1212
help:
1313
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
1414

1515
.PHONY: help Makefile
1616

17+
clean:
18+
rm -rf $(BUILDDIR)/*
19+
1720
# Catch-all target: route all unknown targets to Sphinx using the new
1821
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
1922
%: Makefile

‎docs/make.bat‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@ if "%SPHINXBUILD%" == "" (
88
set SPHINXBUILD=sphinx-build
99
)
1010
set SOURCEDIR=source
11-
set BUILDDIR=build
11+
set BUILDDIR=_build
1212

1313
%SPHINXBUILD% >NUL 2>NUL
1414
if errorlevel 9009 (

‎docs/source/_pages/contact.rst‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,3 @@
1-
==========
2-
Contact Us
3-
==========
1+
#############
2+
Contact Us 📞
3+
#############
Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
###############
2+
Contributing 🎉
3+
###############
4+
5+
**Thanks for your interest!** All contributions are welcome. We feel this library will grow stronger from user contributions, so thank you for your time.
6+
7+
To maintain consistency across the code base (and minimize the introduction of bugs), we follow several guidelines. Every effort has been made to automate this for you using several tools so you can focus on adding features rather than fixing semicolons.
8+
9+
This page is meant to show you how to use these tools and what rules to follow when contributing code. Please read the following sections very carefully.
10+
11+
-----
12+
13+
Guidelines
14+
==========
15+
16+
Being Respectful
17+
----------------
18+
19+
First and foremost, all contributors shall demonstrate empathy and kindness towards each other. This project respects all skill levels and aims to foster an environment where people want to contribute. Please do not talk down or belittle others or their work. For more info, please read the `Code of Conduct`_.
20+
21+
Branching and Versioning Strategy
22+
---------------------------------
23+
24+
``qtpygraph`` adopts a `0-ver`_ / `PEP 440`_-ish style versioning strategy with a `GitHub Flow`_-ish style branching strategy. The rationale for this choice is best summarized as follows:
25+
26+
*"version numbers are just a mapping of a sequence of digits to our branching strategy in source control"*
27+
28+
-- `Brett Cannon`_
29+
30+
Becoming a Maintainer
31+
---------------------
32+
33+
If you feel you can triage problems and mentor junior developers, please consider becoming a maintainer! For more info, please `contact the author`_.
34+
35+
.. _`Code of Conduct`:
36+
code_of_conduct.rst
37+
.. _`0-ver`:
38+
https://0ver.org/
39+
.. _`PEP 440`:
40+
https://peps.python.org/pep-0440/#public-version-identifiers
41+
.. _`GitHub Flow`:
42+
https://docs.github.com/en/get-started/quickstart/github-flow
43+
.. _`Brett Cannon`:
44+
https://snarky.ca/why-i-dont-like-semver/
45+
.. _`contact the author`:
46+

‎docs/source/conf.py‎

Lines changed: 15 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -8,15 +8,17 @@
88
import importlib.resources as rsrc
99
import os
1010
import sys
11-
from importlib import metadata
11+
from datetime import date
12+
13+
import qtpygraph
1214

1315
# -- Project information ----------------------------------------------------------------
1416

1517
project = 'QtPyGraph'
16-
copyright = '2022, Adam Hendry' # pylint: disable=redefined-builtin
18+
copyright = f'2022-{date.today().year}, Adam Hendry' # pylint: disable=redefined-builtin
1719
author = 'Adam Hendry'
1820
root_package = 'qtpygraph'
19-
version = metadata.version(root_package)
21+
version = qtpygraph.__version__
2022
release = version
2123

2224
# -- Path setup -------------------------------------------------------------------------
@@ -27,7 +29,6 @@
2729
packages = [
2830
root / root_package,
2931
root / r'docs',
30-
root / r'logs',
3132
root / r'tests',
3233
]
3334

@@ -46,13 +47,14 @@
4647
'sphinx.ext.intersphinx',
4748
'sphinx.ext.napoleon',
4849
'sphinxcontrib.email',
50+
'sphinxcontrib.mermaid',
4951
]
5052

5153
# -- General configuration --------------------------------------------------------------
5254

5355
# Paths are relative to ``source``
54-
templates_path = ['_templates']
55-
html_static_path = ['_static']
56+
# templates_path = ['_templates']
57+
# html_static_path = ['_static']
5658

5759
source_suffix = '.rst'
5860
master_doc = 'index'
@@ -64,10 +66,11 @@
6466

6567
# -- HTML Output ------------------------------------------------------------------------
6668

67-
html_css_files = [
68-
'css/custom.css',
69-
]
70-
html_style = 'css/style.css'
69+
html_theme = 'sphinx_book_theme'
70+
# html_css_files = [
71+
# 'css/custom.css',
72+
# ]
73+
# html_style = 'css/style.css'
7174

7275
# html_logo = r'./_resources/img/qtpygraph_logo.png'
7376

@@ -79,13 +82,8 @@
7982
html_short_title = project
8083

8184
html_theme_options = {
82-
'display_version': True,
83-
'prev_next_buttons_location': 'bottom',
84-
'collapse_navigation': True,
85-
'sticky_navigation': True,
86-
'navigation_depth': 4,
87-
'includehidden': True,
88-
'titles_only': False,
85+
'repository_url': 'https://github.com/adam-grant-hendry/qtpygraph',
86+
'use_repository_button': True,
8987
}
9088

9189
# Removes the "View Source" hyperlink

‎docs/source/index.rst‎

Lines changed: 12 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -1,21 +1,21 @@
1-
=========
1+
#########
22
QtPyGraph
3-
=========
3+
#########
44

55
A pythonic interface to the ``Qt`` Graphics View Framework using ``qtpy``.
66

77
.. toctree::
8-
:hidden:
9-
:glob:
10-
:maxdepth: 3
11-
:caption: Home Page:
8+
:maxdepth: 2
9+
:caption: Home Page
1210

13-
self
11+
.. toctree::
12+
:maxdepth: 2
13+
:caption: Contributing
14+
15+
_pages/contributing
1416

1517
.. toctree::
16-
:hidden:
17-
:glob:
18-
:maxdepth: 3
19-
:caption: Support:
18+
:maxdepth: 2
19+
:caption: Support
2020

21-
_pages/contact.rst
21+
_pages/contact

0 commit comments

Comments
 (0)