Skip to content

Commit 7c9b50d

Browse files
jalveszjalvesz
authored
Merge pull request #24 from jalvesz/sphinx
Sphinx autodoc and sphinx-fplotlib-gallery extension publishing
2 parents 6d0e2f0 + 7d58318 commit 7c9b50d

45 files changed

Lines changed: 1742 additions & 1 deletion

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.github/workflows/ci.yml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -61,7 +61,7 @@ jobs:
6161

6262
- name: Set up ${{ matrix.compiler }}
6363
id: fortran
64-
uses: fortran-lang/setup-fortran@v2.0.0-beta.9
64+
uses: fortran-lang/setup-fortran@v2.0.0-beta.13
6565
with:
6666
compiler: ${{ matrix.compiler }}
6767
version: latest

‎.github/workflows/docs.yml‎

Lines changed: 146 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,146 @@
1+
name: Docs
2+
3+
# One workflow, three outcomes:
4+
#
5+
# * fortran-lang/fplotlib, push to main: build and publish the production docs
6+
# to that repository's GitHub Pages.
7+
# * A fork, push to its preview branch: build and publish a preview to the
8+
# fork's own GitHub Pages. The branch is the repository variable
9+
# DOCS_PREVIEW_BRANCH, or 'sphinx' when that is not set. Running the workflow
10+
# by hand on a fork publishes whichever branch it was started on.
11+
# * Anything else, pull requests included: build only, and keep the HTML as a
12+
# downloadable artifact.
13+
#
14+
# Publishing needs Settings > Pages > Source set to "GitHub Actions". On a
15+
# fork, the github-pages environment must also allow the preview branch to
16+
# deploy (Settings > Environments > github-pages).
17+
18+
on:
19+
push:
20+
paths: &paths
21+
- 'docs/**'
22+
- 'README.md'
23+
- 'VERSION'
24+
- '.github/workflows/docs.yml'
25+
# The gallery extension the docs are built with.
26+
- 'sphinx-fplotlib-gallery/**'
27+
# The gallery builds the library and runs its examples, and the API
28+
# reference reads the sources.
29+
- 'src/**'
30+
- 'examples/**'
31+
- 'fpm.toml'
32+
pull_request:
33+
paths: *paths
34+
workflow_dispatch:
35+
36+
concurrency:
37+
group: docs-${{ github.ref }}
38+
cancel-in-progress: true
39+
40+
env:
41+
LANG: "en_US.UTF-8"
42+
LC_ALL: "en_US.UTF-8"
43+
PIP_DISABLE_PIP_VERSION_CHECK: "ON"
44+
PIP_NO_CLEAN: "ON"
45+
PIP_PREFER_BINARY: "ON"
46+
TZ: "UTC"
47+
48+
jobs:
49+
build:
50+
name: Build
51+
permissions:
52+
contents: read
53+
runs-on: ubuntu-latest
54+
outputs:
55+
publish: ${{ steps.target.outputs.publish }}
56+
steps:
57+
- uses: actions/checkout@v4
58+
59+
- name: Decide where the docs go
60+
id: target
61+
env:
62+
UPSTREAM: fortran-lang/fplotlib
63+
PREVIEW_BRANCH: ${{ vars.DOCS_PREVIEW_BRANCH || 'sphinx' }}
64+
EVENT: ${{ github.event_name }}
65+
REPO: ${{ github.repository }}
66+
BRANCH: ${{ github.ref_name }}
67+
run: |
68+
publish=none
69+
if [ "$REPO" = "$UPSTREAM" ]; then
70+
if [ "$EVENT" != pull_request ] && [ "$BRANCH" = main ]; then
71+
publish=production
72+
fi
73+
elif [ "$EVENT" = workflow_dispatch ] \
74+
|| { [ "$EVENT" = push ] && [ "$BRANCH" = "$PREVIEW_BRANCH" ]; }; then
75+
publish=preview
76+
fi
77+
echo "publish=$publish" >> "$GITHUB_OUTPUT"
78+
echo "Docs for $REPO@$BRANCH ($EVENT): publish=$publish"
79+
80+
- name: Configure GitHub Pages
81+
if: steps.target.outputs.publish != 'none'
82+
uses: actions/configure-pages@v5
83+
84+
- uses: actions/setup-python@v5
85+
with:
86+
python-version: '3.x'
87+
88+
# The gallery in docs/gallery is built and run during the docs build, so
89+
# the same toolchain the tests use has to be here too.
90+
- name: Set up GFortran
91+
id: fortran
92+
uses: fortran-lang/setup-fortran@v2.0.0-beta.11
93+
with:
94+
compiler: gfortran
95+
version: latest
96+
97+
- uses: fortran-lang/setup-fpm@v10
98+
with:
99+
github-token: ${{ secrets.GITHUB_TOKEN }}
100+
101+
# The gallery extension comes from this checkout rather than from PyPI,
102+
# so the docs always exercise the version being changed.
103+
- name: Install dependencies
104+
run: |
105+
pip install ./sphinx-fplotlib-gallery -r docs/requirements.txt
106+
python --version
107+
sphinx-build --version
108+
ford --version
109+
110+
- name: Build Docs
111+
env:
112+
# Picked up by docs/conf.py as fplotlib_gallery_compiler.
113+
FPM_FC: ${{ steps.fortran.outputs.fc }}
114+
run: sphinx-build -W -b html docs docs/_build/html
115+
116+
- name: Upload the HTML
117+
uses: actions/upload-artifact@v4
118+
with:
119+
name: docs-html
120+
path: ./docs/_build/html/
121+
122+
- name: Upload Pages artifact
123+
if: steps.target.outputs.publish != 'none'
124+
uses: actions/upload-pages-artifact@v4
125+
with:
126+
path: ./docs/_build/html/
127+
128+
deploy:
129+
name: Publish (${{ needs.build.outputs.publish }})
130+
if: needs.build.outputs.publish != 'none'
131+
needs: build
132+
permissions:
133+
pages: write
134+
id-token: write
135+
# Never cancel a deployment half way; queue the next one instead.
136+
concurrency:
137+
group: pages
138+
cancel-in-progress: false
139+
runs-on: ubuntu-latest
140+
environment:
141+
name: github-pages
142+
url: ${{ steps.deployment.outputs.page_url }}
143+
steps:
144+
- name: Deploy to GitHub Pages
145+
id: deployment
146+
uses: actions/deploy-pages@v4

‎.github/workflows/sphinx-fplotlib-gallery.yml‎

Lines changed: 116 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,116 @@
1+
name: sphinx-fplotlib-gallery
2+
3+
# Builds and checks the sphinx-fplotlib-gallery package, and publishes it.
4+
#
5+
# * Pull requests that touch it: build, check and smoke-test the package.
6+
# * A tag sphinx-fplotlib-gallery-vX.Y.Z on fortran-lang/fplotlib: the same,
7+
# then publish to PyPI. The tag must match __version__ in the package.
8+
# * Run by hand with "testpypi": publish to TestPyPI, to try a release out.
9+
#
10+
# Publishing uses PyPI trusted publishing, so no token is stored here. Each
11+
# index needs a trusted publisher for this repository, this workflow file and
12+
# the environment named below ("pypi" or "testpypi").
13+
14+
on:
15+
pull_request:
16+
paths:
17+
- 'sphinx-fplotlib-gallery/**'
18+
- '.github/workflows/sphinx-fplotlib-gallery.yml'
19+
push:
20+
tags:
21+
- 'sphinx-fplotlib-gallery-v*'
22+
workflow_dispatch:
23+
inputs:
24+
index:
25+
description: Where to publish
26+
type: choice
27+
options: [none, testpypi]
28+
default: none
29+
30+
permissions:
31+
contents: read
32+
33+
env:
34+
PIP_DISABLE_PIP_VERSION_CHECK: "ON"
35+
36+
jobs:
37+
build:
38+
name: Build and check
39+
runs-on: ubuntu-latest
40+
steps:
41+
- uses: actions/checkout@v4
42+
43+
- uses: actions/setup-python@v5
44+
with:
45+
python-version: '3.x'
46+
47+
- name: Build
48+
run: |
49+
pip install build twine
50+
python -m build sphinx-fplotlib-gallery --outdir dist
51+
52+
- name: Check the metadata PyPI will render
53+
run: twine check --strict dist/*
54+
55+
- name: Check the tag matches the version
56+
if: startsWith(github.ref, 'refs/tags/')
57+
env:
58+
TAG: ${{ github.ref_name }}
59+
run: |
60+
wheel=$(ls dist/*.whl)
61+
version=$(basename "$wheel" | cut -d- -f2)
62+
if [ "$TAG" != "sphinx-fplotlib-gallery-v$version" ]; then
63+
echo "::error::Tag $TAG does not match the package version $version"
64+
exit 1
65+
fi
66+
67+
# The wheel alone, outside the checkout, so a file missing from it shows.
68+
- name: Smoke test
69+
working-directory: ${{ runner.temp }}
70+
run: |
71+
python -m venv smoke
72+
smoke/bin/pip install "$GITHUB_WORKSPACE"/dist/*.whl
73+
smoke/bin/python -c "import fplotlib_gallery as g; print(g.__file__, g.__version__)"
74+
75+
- uses: actions/upload-artifact@v4
76+
with:
77+
name: sphinx-fplotlib-gallery-dist
78+
path: dist/
79+
80+
pypi:
81+
name: Publish to PyPI
82+
if: startsWith(github.ref, 'refs/tags/') && github.repository == 'fortran-lang/fplotlib'
83+
needs: build
84+
runs-on: ubuntu-latest
85+
environment:
86+
name: pypi
87+
url: https://pypi.org/p/sphinx-fplotlib-gallery
88+
permissions:
89+
id-token: write
90+
steps:
91+
- uses: actions/download-artifact@v4
92+
with:
93+
name: sphinx-fplotlib-gallery-dist
94+
path: dist/
95+
- uses: pypa/gh-action-pypi-publish@release/v1
96+
97+
testpypi:
98+
name: Publish to TestPyPI
99+
if: github.event_name == 'workflow_dispatch' && inputs.index == 'testpypi'
100+
needs: build
101+
runs-on: ubuntu-latest
102+
environment:
103+
name: testpypi
104+
url: https://test.pypi.org/p/sphinx-fplotlib-gallery
105+
permissions:
106+
id-token: write
107+
steps:
108+
- uses: actions/download-artifact@v4
109+
with:
110+
name: sphinx-fplotlib-gallery-dist
111+
path: dist/
112+
- uses: pypa/gh-action-pypi-publish@release/v1
113+
with:
114+
repository-url: https://test.pypi.org/legacy/
115+
# A version can be uploaded only once; trying it again is not an error.
116+
skip-existing: true

‎.gitignore‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -19,3 +19,8 @@ fplotlib_show.svg
1919
# python
2020
__pycache__/
2121
*.pyc
22+
23+
# sphinx / sphinx-gallery
24+
docs/_build/
25+
docs/auto_gallery/
26+
docs/sg_execution_times.rst

‎VERSION‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
0.1.0

‎docs/Makefile‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
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+
# Put it first so that "make" without argument is like "make help".
12+
help:
13+
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
14+
15+
.PHONY: help Makefile
16+
17+
# Catch-all target: route all unknown targets to Sphinx using the new
18+
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
19+
%: Makefile
20+
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

‎docs/api/fplotlib.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
# fplotlib module
2+
3+
```{f:module} fplotlib
4+
```

‎docs/api/fplotlib_artist.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
# fplotlib_artist module
2+
3+
```{f:module} fplotlib_artist
4+
```

‎docs/api/fplotlib_backend_eps.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
# fplotlib_backend_eps module
2+
3+
```{f:module} fplotlib_backend_eps
4+
```

‎docs/api/fplotlib_backend_pdf.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
# fplotlib_backend_pdf module
2+
3+
```{f:module} fplotlib_backend_pdf
4+
```

0 commit comments

Comments
 (0)