From c4315f4c582e74b48a83af43a4aa05d4ac2a86f7 Mon Sep 17 00:00:00 2001 From: Michele Mesiti Date: Thu, 24 Sep 2026 20:23:21 +0200 Subject: [PATCH 1/3] use requirements.txt in pages workflows Updated the workflow to install dependencies from requirements.txt instead of hardcoding them. Also, Added instructions about changing requirements.txt adding sphinx-autodoc2 and myst-nb packages in the relevant exercises. --- content/gh_workflow.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/content/gh_workflow.md b/content/gh_workflow.md index 6c363b49..96526526 100644 --- a/content/gh_workflow.md +++ b/content/gh_workflow.md @@ -64,7 +64,7 @@ jobs: - uses: actions/setup-python@v5 - name: Install dependencies run: | - pip install sphinx sphinx_rtd_theme myst_parser + pip install -r requirements.txt - name: Sphinx build run: | sphinx-build doc _build @@ -125,14 +125,14 @@ What do you need to change in the workflow file? ```{solution} Solution 1. **API documentation** - 1. Change line 16 of `.github/workflows/documentation.yml` from `pip install sphinx sphinx_rtd_theme myst_parser` to `pip install sphinx sphinx_rtd_theme myst_parser sphinx-autodoc2`. + 1. Edit the `requirements.txt` file in the repository, adding the `sphinx-autodoc2` package. 2. Follow the instructions in [Sphinx-3](#api-exercise) changing paths so that: 1. `multiply.py` is `src/multiply.py` and is specified as `../src/multiply.py` in the `autodoc2_packages` preference in `conf.py` 2. `conf.py` is `doc/conf.py` 3. `index.md` is `doc/index.md`. 3. Commit and push your changes, verify the action has run successfully, and view the built site in your browser. 2. **a Jupyter notebook** - 1. Change line 16 of `.github/workflows/documentation.yml` from `pip install sphinx sphinx_rtd_theme myst_parser` to `pip install sphinx sphinx_rtd_theme myst_parser myst-nb`. + 1. Edit the `requirements.txt` file in the repository, adding the `myst-nb` package. 2. Follow the instructions in [Sphinx-4](#jupyter-exercise) changing paths so that: 1. `flower.md` is `doc/flower.md` 2. `conf.py` is `doc/conf.py` From 3e78230c09349502fc508b31cb113f5245ba6818 Mon Sep 17 00:00:00 2001 From: Michele Mesiti Date: Tue, 22 Sep 2026 23:13:02 +0200 Subject: [PATCH 2/3] Add gitlab version for deploying sphinx doc from https://github.com/mmesiti/cr-best-practices-in-rse/blob/98b7940782ff1c3cdfb55a433e9d60f735b8f94c/content/gh_workflow.md Addresses #342 --- content/gh_workflow.md | 166 +++++++++++++++++++++++++++++++++++------ 1 file changed, 143 insertions(+), 23 deletions(-) diff --git a/content/gh_workflow.md b/content/gh_workflow.md index 96526526..30e37c64 100644 --- a/content/gh_workflow.md +++ b/content/gh_workflow.md @@ -1,16 +1,17 @@ -# Deploying Sphinx documentation to GitHub Pages +# Deploying Sphinx documentation ```{objectives} - Create a basic workflow which you can take home and adapt for your project. ``` -## [GitHub Pages](https://pages.github.com/) +## [GitHub Pages](https://pages.github.com/) and [GitLab Pages](https://docs.gitlab.com/user/project/pages/) -- Serve websites from a GitHub repository. +- Serve websites from a Git repository. - It is no problem to serve using your own URL `https://myproject.org` instead of `https://myuser.github.io/myproject`. -## [GitHub Actions](https://github.com/features/actions/) + +## [GitHub Actions](https://github.com/features/actions/) and [GitLab CI/CD](https://docs.gitlab.com/topics/build_your_application/) - Automatically runs code when your repository changes. - We will let it run `sphinx-build` and make the result available to GitHub Pages. @@ -19,23 +20,80 @@ ## Our goal: putting it all together - Host source code with documentation sources on a public Git repository. -- Each time we `git push` to the repository, a GitHub action triggers to +- Each time we `git push` to the repository, + a GitHub workflow or a Gitlab pipeline + triggers to rebuild the documentation. -- The documentation is pushed to a separate branch called 'gh-pages'. --- -## Demonstration - Deploy Sphinx documentation to GitHub Pages +## Demonstration - Deploy Sphinx documentation to GitHub/GitLab Pages + +::::::{exercise} GH-Pages-1: Deploy Sphinx documentation to GitHub Pages +In this exercise we will create an example repository on a software forge +(GitHub or GitLab) +and deploy it to the corresponding "Page" service +(GitHub Pages or GitLab Pages). + +**Preliminary: Verify the "Pages" feature is available on your forge** + +:::::{tabs} +::::{group-tab} GitHub +On `github.com`, the feature is typically available. +:::: +::::{group-tab} GitLab +On GitLab servers, it depends on the configuration. +- On `gitlab.com`, the feature is typically available. +- On other instances, you have to check. + You can verify that in a project you have on that GitLab instance. + Go to the page of a project, on **Settings** -> **General** -> **Visibility, project features, permissions** and check if the **Pages** can be activated. + If not, then your GitLab instance might not allow you to host pages, + and you will need another instance or service to host your static website. +:::: +::::: + +**Step 1**: -````{exercise} GH-Pages-1: Deploy Sphinx documentation to GitHub Pages -In this exercise we will create an example repository on GitHub and -deploy it to GitHub Pages. +Generate the repository to be used as the starting point. +Repositories can be generated from templates, +created from imports, or created as empty and filled with a push +from you own machine. -**Step 1**: Go to the [documentation-example](https://github.com/coderefinery/documentation-example/generate) project template + +:::::{tabs} +:::{group-tab} GitHub +On GitHub the most convenient way is to generate the repository from a template. + +Go to the [documentation-example](https://github.com/coderefinery/documentation-example/generate) project template on GitHub and create a copy to your namespace. - Give it a name, for instance "documentation-example". - You don't need to "Include all branches" - Click on "Create a repository". +::: +:::{group-tab} GitLab +Oh GitLab, althoug a "template" feature is present, +its use is more constrained, so we will instead *import* +the template repository from GitHub. + +- Go to your account on the GitLab instance you plan to use, +click on the `+` icon at the top of the page on the right, +and click on "New Project/Repository". +- Click on the "Import Project" tile, then on "Repository by URL" +- In the "Git repository URL" field, paste `https://github.com/coderefinery/documentation-example`, + and click the "Check connection" button, which is immediately on the right. +- You also need to choose: + - a project name, for instance "documentation-example" + - an appropriate group or namespace. Your personal namespace is fine. + - a visibility level: choose "public", + otherwise the pipelines you create + will not be able to run on "public" infrastructure. + +After that, click on "Create Project". +You will see that GitLab is basically cloning the GitHub project. + +::: +::::: + **Step 2**: Browse the new repository. - It will look very familar to the previous episode. @@ -44,9 +102,11 @@ on GitHub and create a copy to your namespace. - The source code for your project could then go under `src/`. -**Step 3**: Add the GitHub Action to your new Git repository. +**Step 3**: Automate the generation of the documentation. +:::::{tabs} +::::{group-tab} GitHub - Add a new file at `.github/workflows/documentation.yml` (either through terminal or web interface), containing: -```{code-block} yaml +:::{code-block} yaml :linenos: :emphasize-lines: 16,19 name: documentation @@ -76,7 +136,7 @@ jobs: github_token: ${{ secrets.GITHUB_TOKEN }} publish_dir: _build/ force_orphan: true -``` +::: - You don't need to understand all of the above -- you should mainly pay attention the highlighted lines which are shell commands (we know this because they are part of a `run: |` section). @@ -85,9 +145,36 @@ jobs: - After the file has been committed (and pushed), check the action at `https://github.com/USER/documentation-example/actions` (replace `USER` with your GitHub username). +:::: +::::{group-tab} GitLab + +On GitLab, automation is typically managed by the `.gitlab-ci.yml` file +at the top directory of your repository. -**Step 4**: Enable GitHub Pages -- On GitHub go to "Settings" -> "Pages". +Create that file (if not existing), and add the definition of a new job in it: +:::{code-block} yaml +:linenos: +:emphasize-lines: 4,5 +create-pages: + image: python:latest + script: + - pip install sphinx sphinx_rtd_theme myst_parser + - sphinx-build doc public + pages: true +::: +:::: +::::: + + +**Step 4**: Enable Pages feature and verify it's running + +:::::{tabs} +::::{group-tab} GitHub +Note that once the documentation created +it is pushed to a separate branch called 'gh-pages' +(this is what the action `peaceiris/actions-gh-pages` does). + +- Go to "Settings" -> "Pages". - Under "Build and deployment" - In the **Source** section: choose "Deploy from a branch" in the dropdown menu - In the **Branch** section: choose "gh-pages" and "/ (root)" in the dropdown menus @@ -95,14 +182,50 @@ jobs: - You should now be able to verify the pages deployment in the "Actions" list ([this is how it looks like](https://github.com/coderefinery/documentation/actions) for this lesson material). +- You can verify that the repository has now a branch named `gh-pages` + which contains the generated documentation + (and only that). +:::: +::::{group-tab} GitLab + With the default settings, on a GitLab server with the Pages feature enabled +everything should work. To check: + +- Go to Build -> Pipelines. + There should be a running (or complete) pipeline at the top of the list, + with two stages. + + - if you see only one stage, the "Pages" feature might not be active for your repository or for the whole instance + - if you see no pipelines, then the CI/CD feature might be disabled, or you might have misnamed the `.gitlab-ci.yml` file. + + (the project features can be checked in **Settings**->**General**->***Visibility, project features, permissions**) + +:::: +::::: + + + **Step 5**: Verify the result -- Your site should now be live on `https://USER.github.io/documentation-example/` (replace USER). +:::::{tabs} +::::{group-tab} GitHub +Your site should now be live at +`https://USER.github.io/documentation-example/` (replace USER). + +:::: +::::{group-tab} GitLab +Your site should be live. +To find out the exact URL, +go to the main page of your project +and on the right +(under the "Project Information" header) +click on the "GitLab Pages" link). +:::: +::::: **Step 6 (optional)**: Verify refreshing the documentation - Commit some changes to your documentation - Verify that the documentation website refreshes after your changes (can take few seconds or a minute) -```` +:::::: ## Exercise - Sphinx documentation on GitHub Pages ````{exercise} GH-Pages-2: Putting it all together @@ -145,10 +268,7 @@ What do you need to change in the workflow file? ``` ```` -## Alternatives to GitHub Pages - -- [GitLab Pages](https://docs.gitlab.com/ee/user/project/pages/) - and [GitLab CI](https://docs.gitlab.com/ee/ci/) can create a very similar workflow. +## Alternatives to GitHub and GitLab Pages - [Read the Docs](https://readthedocs.org) is the most common alternative to hosting in GitHub Pages. @@ -173,5 +293,5 @@ What do you need to change in the workflow file? ```{keypoints} - Sphinx makes simple HTML (and more) files, so it is easy to find a place to host them. - Github Pages + Github Actions provides a convenient way to make - sites and host them on the web. + sites and host them on the web, and GitLab offers a similar workflow. ``` From 566f33b24066480e9be7f3230cb19e13581f29c5 Mon Sep 17 00:00:00 2001 From: Michele Mesiti Date: Thu, 24 Sep 2026 20:35:44 +0200 Subject: [PATCH 3/3] Use requirements.txt in gitlab version --- content/gh_workflow.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/gh_workflow.md b/content/gh_workflow.md index 30e37c64..ae0ce88a 100644 --- a/content/gh_workflow.md +++ b/content/gh_workflow.md @@ -158,7 +158,7 @@ Create that file (if not existing), and add the definition of a new job in it: create-pages: image: python:latest script: - - pip install sphinx sphinx_rtd_theme myst_parser + - pip install -r requirements.txt - sphinx-build doc public pages: true :::