#29 GitHub actions to automate documentation site build on new release #100

dimtsap · 2025-07-22T15:37:15Z

@dskarbrevik @dylanbouchard
I guess that took a bit longer than everyone expected but finally, I have the automated documentation github action ready for your review (#29). I have made some structural changes to how you build the docs so far so that you don't have to track multiple branches from now on. I will break down these changes as well as minor things that you will need to configure for this to work without any issues.

So let me begin with the major points:

Docs source is moved to main: Initially your gh-pages folder contained both a copy of your code as well as the docs and the build docs that were finally deployed. That meant for that for each code update you needed to track both main and gh-pages branches and make sure that they are align which I know can quickly become cumbersome. Moving the docs to main allows you to keep your focus to one place, while docs updates are built and deployed automatically. Also The gh-pages branch is no longer polluted with code that shouldn't live in the docs deployment as it can now be an orphan branch and only build docs live there now. (e.g. https://github.com/DTsapetis/uqlm/tree/gh-pages).
The docs dependencies are moved from a requirements.txt inside the docs folder to an optional dependencies group inside the pyproject toml to match the rest of the code dependencies. Just FYI you need to update the poetry lock file in case you agree with this change.
Two files are added in the .github/workflows folder. One for the docs that is triggered when tags are created and a python file that computes the version.json

For the minor issues:

You will need to create a repository variable named PANDOC_VERSION, which will have the version you use. I didn't want to make it hardcoded in the workflow file.
In the new and now orphan gh-pages branch you need to have two initial files. An index.html that redirects you to the latest version the first time you navigate to the gh-pages. (https://github.com/DTsapetis/uqlm/blob/gh-pages/index.html) I think you have a file like that one in your docs too. And also a .nojekyll file like the one here (https://github.com/DTsapetis/uqlm/blob/gh-pages/.nojekyll).
You can have a look at how the docs will look like with the dropdown here. (https://dtsapetis.github.io/uqlm/latest/index.html) In this version the sequence of the builds is not in the correct order because the versions were compared as strings to sort them. In my last commit it is now fixed and the versions are parsed and compared. It is tested locally to make sure it now finds the correct order.
I made several commits when trying out the workflow, so I would suggest you squash them.

Let me know if you have any comments or questions about the whole workflow.

dylanbouchard · 2025-07-25T19:58:32Z

@doyajii1 do you mind reviewing this one when you get a chance?

doyajii1 · 2025-08-08T14:20:45Z

@dimtsap These are great effort to automate doc site build! I will add points I think we need to change but feel free to ask/discuss on this together.

doyajii1 · 2025-08-08T14:26:03Z

.github/workflows/documentation.yaml

+        run: |
+          echo "Tag: ${{ steps.get_tag.outputs.tag }}"
+
+      - name: Extract version without "v"


We want to pick out just major version strings like "v0.1", "v0.2" instead of v0.1.2, v0.2.1 from TAGs. I can imagine we could have a python script to filter them out and send to $GITHUB_OUTPUT variable but unsure if there is a better way. If we can handle this up in the front, I hope that the other steps should overwrite to same major release doc site folder when the minor release gets pushed.

If you can define internally your version strategy for the documentation that would be really helpful. The initial issue stated that the documentation should be triggered on new releases, this is why I used the current approach. Please let me know which versions you want to display and how the gh-pages branch should behave (folder structure, file replacement etc) to adjust it.

@dimtsap Thank you for continuing to work on this! :) I think your current PR folder structure looks good; it's just that we want to track up to the minor releases for the documentation site, such as "v0.1", "v0.2", ..., "v0.#". I hope there is a way to overwrite the minor release folder whenever a patch tag is pushed.

I was thinking more along the following lines, but I'm unsure if it sounds possible to make it work:

A push happens for v* tags.

The Show tag step runs as it is.

The Set up Python step runs to set up the Python script executable environment.

A Python script extracts the version name up to the minor digit at a new Extract version without "v" step.

The rest of the steps use the minor digit folder name. (Maybe delete and write a new one?)

Is it sounded possible?

doyajii1 · 2025-08-08T14:32:17Z

.github/workflows/documentation.yaml

+        run: |
+          pip install poetry
+
+      - name: Download and install Pandoc 3.7.0.2


Not important but can we remove Pandoc version from the step name?

doyajii1 · 2025-08-08T14:33:45Z

docs/Makefile

+# Get the parent dir name which is this docs' version
+VERSION := $(notdir $(CURDIR))
+
+install:


Now that pyproject.toml has the requirements.txt contents, can we remove install? I think the github and test local can be updated in the other PR for fast local testing in the future.

Should be possible to remove but I'll double check that.

doyajii1 · 2025-08-08T14:44:41Z

Thank you for keeping all of docs dependencies versions as it is. We had some issues when people attempted to build doc site src on different python versions.

dimtsap · 2025-08-26T19:09:42Z

@doyajii1 All changes you requested are implemented and work only for the minor version of documention like you asked. You can have a look at my example deployments here (https://dtsapetis.github.io/uqlm/latest/) Let me know if you have any other comments.

doyajii1 · 2025-08-30T18:09:08Z

@dimtsap Forgive me for checking so late at this, I will stay more tuned to give back feedback faster.

Thank you for keep working through this PR. My explanation might have been confusing and forgive me on that part. The entire goal was basically can we just get v0.1, v0.2, v0.3, ... v#.# in the version selector dropdown without a file with list of version strings based on version tag. This is current version pattern in the drop down menu:

I added this comment based on your newer build has pattern of v3.0, v3.1.

Sorry for being so picky and difficult to have this move forward. Please don't get me wrong, I do feel your work is very close and very essential for the UQLM to avoid manual builds at every version release.

dimtsap · 2025-08-30T18:50:19Z

@doyajii1 I am not sure I understand the comment you made above. The changes I propose automatically build the documentation based on the latest tag you publish. In addition the version.json is auto-updated so there is no need to maintain it manually. And to my understanding the version selector depends on such a file ( version.json)for the sphinx theme you have chosen. Could you please let me know which part of the process I have misunderstood to address it?

doyajii1 · 2025-08-30T19:15:57Z

@dimtsap thank you for the comment. I will try to show with example image. As of now the versions that I am seeing on your test site from forked repo is showing v3.1, v3.0. Our pattern is to keep track of v0.#.

Yours:

Expected:

doyajii1 · 2025-08-30T19:38:01Z

I looked back at your forked repo and realized that you have created tags on your forked repo which generated different version patterns. Can you test again just to ensure with same release tags? I believe your code and scripts should be good. It's just that your forked repo release tags are different to actual current UQLM release tags.

What would be procedure to keep previous version docs? would it be something like recreate release tags?

dimtsap · 2025-09-03T17:07:19Z

I looked back at your forked repo and realized that you have created tags on your forked repo which generated different version patterns. Can you test again just to ensure with same release tags? I believe your code and scripts should be good. It's just that your forked repo release tags are different to actual current UQLM release tags.

What would be procedure to keep previous version docs? would it be something like recreate release tags?

Hi @doyajii1. I recreated the releases of my repo so that the documentation looks similar to the one of yours. You can have a look at the result here: https://dtsapetis.github.io/uqlm/latest/ To keep the previous docs the only thing you need to do it to make you gh-pages look like that:

What this means:

Folder v0.1 with build docs of v0.1 (make sure the v is in the folder name)
Folder v0.2 with build docs of v0.2 (make sure the v is in the folder name)
Current version.json file
Current .nojekkyl file
Current index.html file

No other file is needed in the gh-pages branches. As you can see in the PR the docs are moved to the same branch as your code. You will not need to maintain multiple branches any more. Just update the docs when you need. And when you publish a new tag (make sure it has the pattern vMajor.Minor.Patch) the documentation will be updated automatically. Let me know if you have any other commnets or questions.

doyajii1 · 2025-09-03T21:37:49Z

@dimtsap All looks great! Thank you for your additional explanation and test.

Add FAQ page file
https://github.com/cvs-health/uqlm/blob/gh-pages/docs_src/latest/source/faqs.rst
Add it to the index.rst file
Example in the bottom of this script: https://github.com/cvs-health/uqlm/blob/gh-pages/docs_src/latest/source/index.rst
Would you create parallel PR to gh-pages branch with a right folder structure? I think both of changes need to be applied together?

After these add into the PR, it seems we are all ready @dylanbouchard and @mohitcek

dimtsap added 30 commits July 15, 2025 12:56

Add files via upload

8abd429

Create documentation.yaml

1852f86

Update documentation.yaml

c96b44e

Update documentation.yaml

cb3a656

Update documentation.yaml

b472920

Update documentation.yaml

420863f

Update documentation.yaml

a9a3e37

Update documentation.yaml

0b00705

Update documentation.yaml

dda7c39

Update documentation.yaml

a8e3b26

Update documentation.yaml

ba54ae8

Update conf.py

384c1aa

Moves docs/requirements to pyproject.toml

f060edd

Update documentation.yaml

c0097ab

Update documentation.yaml

f9a35ff

Update documentation.yaml

050ed3f

Update documentation.yaml

98072e0

Update documentation.yaml

bd83c9a

Create update_version_json.py

10c8075

Update documentation.yaml

1809a3a

Update documentation.yaml

a9dd334

Update documentation.yaml

284c81b

Update update_version_json.py

0d6d8c1

Update documentation.yaml

1b421dd

Update documentation.yaml

245f067

Update documentation.yaml

1757175

Update documentation.yaml

8abca4c

Update update_version_json.py

a312826

Update update_version_json.py

4e57fe5

Update update_version_json.py

fdc0256

dimtsap added 6 commits July 22, 2025 14:11

Updates version.json file

04595b9

Update documentation.yaml

57c8b70

Update documentation.yaml

85852bd

Update update_version_json.py

a18b25a

Sorts gh-pages folder chronologically

02facb5

Sorts gh-pages folders by parsing version number

fabc65d

doyajii1 suggested changes Aug 8, 2025

View reviewed changes

dimtsap added 4 commits August 12, 2025 12:15

Removes pandoc version

989954f

Update Makefile

b4805da

Update documentation.yaml

d32b2b4

Deletes old contents of versioned and latest folders

ae434f9

dylanbouchard requested a review from doyajii1 August 19, 2025 13:56

Update documentation.yaml

0f79ca1

dimtsap added 2 commits September 5, 2025 17:54

Create faqs.rst

71cb8c6

Update index.rst

9bfd946

#29 GitHub actions to automate documentation site build on new release #100

Are you sure you want to change the base?

#29 GitHub actions to automate documentation site build on new release #100

Uh oh!

Conversation

dimtsap commented Jul 22, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

dylanbouchard commented Jul 25, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

doyajii1 commented Aug 8, 2025

Uh oh!

doyajii1 Aug 8, 2025

Choose a reason for hiding this comment

Uh oh!

dimtsap Aug 11, 2025

Choose a reason for hiding this comment

Uh oh!

doyajii1 Aug 12, 2025

Choose a reason for hiding this comment

Uh oh!

doyajii1 Aug 8, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

doyajii1 Aug 8, 2025

Choose a reason for hiding this comment

Uh oh!

dimtsap Aug 11, 2025

Choose a reason for hiding this comment

Uh oh!

doyajii1 commented Aug 8, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

dimtsap commented Aug 26, 2025

Uh oh!

doyajii1 commented Aug 30, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

dimtsap commented Aug 30, 2025

Uh oh!

doyajii1 commented Aug 30, 2025

Uh oh!

doyajii1 commented Aug 30, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

dimtsap commented Sep 3, 2025

Uh oh!

doyajii1 commented Sep 3, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

dimtsap commented Jul 22, 2025 •

edited

Loading

dylanbouchard commented Jul 25, 2025 •

edited

Loading

doyajii1 Aug 8, 2025 •

edited

Loading

doyajii1 commented Aug 8, 2025 •

edited

Loading

doyajii1 commented Aug 30, 2025 •

edited

Loading

doyajii1 commented Aug 30, 2025 •

edited

Loading

doyajii1 commented Sep 3, 2025 •

edited

Loading