Skip to content

Conversation

@ObadaS
Copy link
Collaborator

@ObadaS ObadaS commented Aug 5, 2025

A brief description of the purpose of the changes contained in this PR.

Added mkdocs based documentation files for the new wiki.
For now, I am using uv to build and run the tools needed to build the wiki (similar tool to Poetry)

Once uv is installed, you can build the website with PDF=1 uv run mkdocs build, or use PDF=1 uv run mkdocs serve to make mkdocs serve the website on a localhost address.

I am using mike to add versions to the wiki. To use it, if you already have the gh-pages branch on your machine, you can just run this command : uv run mike serve

If you don't have the gh-pages branch, or if you want to deploy a new version of the wiki, you can use the following commands:

PDF=1 uv run mike deploy -u *versionNumber* *alias*

  • versionNumber will be the version of Codabench that the wiki is for (1.19.0 for example)
  • alias is the version alias. We use latest for the wiki that is build for the master branch of Codabench, and Dev for the wiki that is build for the develop branch of Codabench
  • -u allows mike to override a versionNumber if it already exists

You then have to set the default target for mike to use with the following command: `uv run mike set-default latest``

Once this is done, you can run uv run mike serve to see the latest version of the wiki as well as previous versions (if available) from the dropdown menu on the top left of the wiki.
Note that the version of the wiki should always match the version of Codabench.

I added an automated workflow for Github Action to rebuild the wiki each time there is a change in the develop branch and when we create a new tag for production.

  • For the Develop branch, it will publish the wiki on a dev alias which is not shown by default to users loading the wiki
  • For the Master branch, the workflow will re-create the wiki automatically after we assign a new tag to the release. The workflow will change the default version of the wiki to the latest release.

Checklist

  • Code review by me
  • Hand tested by me
  • I'm proud of my work
  • Code review by reviewer
  • Hand tested by reviewer
  • CircleCi tests are passing
  • Ready to merge

@Didayolo Didayolo merged commit df2eb18 into develop Aug 14, 2025
1 check was pending
@Didayolo Didayolo deleted the mkdocsDocumentation branch August 14, 2025 14:48
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants