switch from RTD to GitHub Pages (#8)

mdtanker · web-flow · commit 6e6498246d75 · 2025-07-16T15:57:59.000+02:00
* switch from RTD to GitHub Pages

* fix uvx in documentation action

* add astral setup-uv to documentation action

* build API docs in action

* remove outdated packagename api file

* remove docs/api folder

* fix nbgallery errors in docs

* style fixes

* install pandoc in action

* temporarily remove publishing site only for main

* specify where docs are built in action

* use sphinx githubpages extension

* fix sphinx build location

* update readme

* enable preview of site in PR's

* fixing PR preview

* seperate deploy from preview actions

* add bash to deplot docs action

* fix docs preview action

* fix docs preview action
diff --git a/.github/workflows/docs_preview.yml b/.github/workflows/docs_preview.yml
@@ -0,0 +1,65 @@
+name: Docs Preview
+
+on:
+  pull_request:
+    types:
+      - opened
+      - synchronize
+      - reopened
+      - edited
+      - closed
+    branches:
+      - "main"
+  workflow_dispatch:
+
+concurrency: preview-${{github.ref}}
+
+jobs:
+  preview:
+    runs-on: ubuntu-latest
+    # only run if from the same repository, not a fork
+    if: github.event.pull_request.head.repo.full_name == github.repository
+    permissions:
+      contents: write
+      pull-requests: write
+    defaults:
+      run:
+        shell: bash -l {0}
+
+    steps:
+      # Checkout current git repository
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      # setup python env
+      - uses: actions/setup-python@v5
+        if: github.event.action != 'closed' # Skip the build if the PR has been closed; just run the clean up steps
+        with:
+          python-version: "3.x"
+
+      - uses: astral-sh/setup-uv@v6
+
+      - id: install_pandoc
+        run: sudo apt-get install pandoc
+
+      # Make API docs
+      - name: Make API docs
+        if: github.event.action != 'closed'
+        run: uvx nox -s build_api_docs
+
+      # Build the documentation
+      - name: Build the documentation
+        if: github.event.action != 'closed'
+        run: uvx nox -s docs --non-interactive -- docs/_build/html
+
+      # Deploy the preview of the docs
+      - name: Deploy Preview
+        uses: rossjrw/pr-preview-action@v1
+        with:
+          source-dir: docs/_build/html
+          preview-branch: gh-pages
+          # custom-url:
+          umbrella-dir: pr-preview
+          action: auto
+          deploy-repository: ${{ github.repository }}
+          token: ${{ secrets.GITHUB_TOKEN }}
diff --git a/.github/workflows/documentation.yml b/.github/workflows/documentation.yml
@@ -0,0 +1,51 @@
+name: documentation
+
+on:
+  push:
+    branches:
+      - main
+  workflow_dispatch:
+
+# This job installs dependencies, builds the html, and pushes it to gh-pages
+jobs:
+  docs:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    concurrency:
+      group: ${{ github.workflow }}-${{ github.ref }} # only run one of these jobs at a time
+    defaults:
+      run:
+        shell: bash -l {0}
+
+    steps:
+      # Checkout current git repository
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      # setup python env
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.x"
+
+      - uses: astral-sh/setup-uv@v6
+
+      - id: install_pandoc
+        run: sudo apt-get install pandoc
+
+      # Make API docs
+      - name: Make API docs
+        run: uvx nox -s build_api_docs
+
+      # Build the documentation
+      - name: Build the documentation
+        run: uvx nox -s docs --non-interactive -- docs/_build/html
+
+      # Deploy the HTML to gh-pages branch
+      - name: GitHub Pages action
+        uses: peaceiris/actions-gh-pages@v4
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: docs/_build/html
+          publish_branch: gh-pages
+          force_orphan: true
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
@@ -92,4 +92,3 @@ repos:
     hooks:
       - id: check-dependabot
       - id: check-github-workflows
-      - id: check-readthedocs
diff --git a/.readthedocs.yaml b/.readthedocs.yaml
diff --git a/README.md b/README.md
@@ -138,13 +138,14 @@ Steps:
     - create a new folder : `staged-recipes/recipes/samplepackagename`
     - copy your `meta.yaml` file into this folder, remove the `meta.yaml` from wherever it was generated.
     - commit and push your changes to your fork, and in the main [repository](https://github.com/conda-forge/staged-recipes) open a PR.
-13) Set up ReadTheDocs for the documentation website
-    - log into ReadTheDocs using your GitHub account.
-    - click `Add project` and ssearch for your repository.
-    - Chose your project name, ideally its the same as your package name, but it doesn't have to be. If it's different, update the badge below: `[rtd-link]: https://samplepackagename.readthedocs.io/en/latest/?badge=latest`
-    - Go to `settings` to update anything you'd like
-        - check `Build pull requests for this project`.
-    - for each commit to main, ReadTheDocs should automatically update the documentation website. Also, in PR's there should be a link to view the new docs to check them before merging the PR.
+13) Set up GitHub Pages to host the documentation website
+    - this will only work for a public repository
+    - On GitHub, go to your repositories settings
+    - for `Source`, choose "Deplot from a branch"
+    - for `Branch`, choose "gh-pages"
+    - for `Select folder`, choose "root"
+    - optionally choose a custom URL and hit save
+    - for every push to `main` (from a PR), the site will be updated
 14) Finalize
     - remove all the above instructions and raise any issues in this template's repository if you have any suggestion or found any errors in this template!
     - if you want, please submit a PR to this repository to add your package to this list at the top of this README to showcase it!
@@ -153,7 +154,7 @@ Steps:
 Short description of your package.
 
 [![Actions Status][actions-badge]][actions-link]
-[![Documentation Status][rtd-badge]][rtd-link]
+[![Documentation Status][website-badge]][website-link]
 
 [![PyPI version][pypi-version]][pypi-link]
 [![Conda-Forge][conda-badge]][conda-link]
@@ -173,8 +174,8 @@ Short description of your package.
 [pypi-link]:                https://pypi.org/project/samplepackagename/
 [pypi-platforms]:           https://img.shields.io/pypi/pyversions/samplepackagename
 [pypi-version]:             https://img.shields.io/pypi/v/samplepackagename
-[rtd-badge]:                https://readthedocs.org/projects/samplepackagename/badge/?version=latest
-[rtd-link]:                 https://samplepackagename.readthedocs.io/en/latest/?badge=latest
+[website-badge]:            https://github.com/mdtanker/python_package_template/actions/workflows/pages/pages-build-deployment/badge.svg
+[website-link]:             https://mdtanker.github.io/python_package_template/
 
 <!-- prettier-ignore-end -->
 
diff --git a/docs/api/packagename.rst b/docs/api/packagename.rst
diff --git a/docs/api/samplepackagename.rst b/docs/api/samplepackagename.rst
diff --git a/docs/conf.py b/docs/conf.py
@@ -18,6 +18,8 @@
     "sphinx_copybutton",
     # "sphinx.ext.viewcode",
     "nbsphinx",
+    # githubpages just adds a .nojekyll file
+    "sphinx.ext.githubpages",
 ]
 
 source_suffix = [".rst", ".md"]
diff --git a/docs/examples/index.md b/docs/examples/index.md
@@ -1,7 +1,11 @@
 # Examples
 
+<!--
 ```{nbgallery}
 ---
 ---
-<!-- Add list of notebooks here -->
+notebook1
+notebook2
+notebook3
 ```
+-->
diff --git a/docs/how_to/index.md b/docs/how_to/index.md
@@ -1,7 +1,11 @@
 # How-To Guides
 
+<!--
 ```{nbgallery}
 ---
 ---
-<!-- Add list of notebooks here -->
+notebook1
+notebook2
+notebook3
 ```
+-->
diff --git a/docs/tutorials/index.md b/docs/tutorials/index.md
@@ -4,9 +4,14 @@ These tutorials are designed to introduce a new user to the software.
 They expect you to be familiar with Python and have the package [successfully installed](../install.md).
 You should follow these in order, then refer to the [how-to guides](../how_to/index.md) for more in-depth guides for specific features.
 
+
+<!--
 ```{nbgallery}
 ---
 "numbered":
 ---
-<!-- Add list of notebook names here -->
+notebook1
+notebook2
+notebook3
 ```
+-->

Original file line number	Diff line number	Diff line change
`@@ -18,6 +18,8 @@`
`18`	`18`	`"sphinx_copybutton",`
`19`	`19`	`# "sphinx.ext.viewcode",`
`20`	`20`	`"nbsphinx",`
	`21`	`+ # githubpages just adds a .nojekyll file`
	`22`	`+ "sphinx.ext.githubpages",`
`21`	`23`	`]`
`22`	`24`
`23`	`25`	`source_suffix = [".rst", ".md"]`