A unified GAMB2LE mkdocs site¶
Here you'll find the meta-documentation. GAMB2LE has decided that our documentation files should live alongside our code in the various appropriate repos. Thus this portal pulls in the documentation from all our code repos and makes a unified documentation site. To do this takes some configuration. We've setup mkdocs to pull (via github actions) from our various repos and make a unified page. There are some steps that you need to take to add a new repo to the documentation. All documentation is compiled into a static webpage (https://gamb2le.pages.dev/) via actions and then uploaded to cloudflare where they're hosted.
Editing and adding to the current docs¶
There are three steps to add a new repo to the docs webpage. (1) Add approporiate mkdocs config to the repo (2) Modify the central mkdocs-portal configuration to pull in the repo via config/CI (3) add the appropriate keys to get permission for github CI automation
(1) To add a new repo to the mkdocs-portal, you must clone the mkdocs template repo. There are three key pieces that must be in your repo from the template:
mkdocs.yml(tells mkdocs what docs files you want included)docs/index.md(points to README.md, so the README is the first docs page).github/workflows/trigger-docs.yml(tells github actions to trigger a new portal build)
(2) Once those are in your repo, you must edit the central mkdocs-portal so that it includes your documentation in the menu and more. You must add your repo to nav in mkdocs.yml around line 35 as:
And then also to mkdocs-portal/.github/workflows/docs.yml so that it's built into
the portal. This is near line 32:
run: |
mkdir -p repos
git clone --depth 1 https://x-access-token:${GH_TOKEN}@github.com/GAMB2LE/your-new-repo.git repos/your-new-repo
(3) Finally, you need to give your repo the keys to have permission to run the actions. For github to build the mkdocs site, each repo needs to have the "private key". So you have to open "settings" and click "secrets" and then click "actions". When you get there you have to add two secrets. They are:
APP_ID = 2899200 APP_PRIVATE_KEY = copy paste the key out of this file
Then builds will auto trigger any time the docs change.
How to setup github (1-time thing, but documented here)¶
These are the steps Michael took to configure a github app to follow the actions above. To setup CI/triggers/actions as an organization you have to create a "github app" for the organization (GAMB2LE) and then generate a personal access token. That way the CI scripts can pull in all the docs from across the repos.
Generating a personal access token and using it for portal builder¶
Go to your GAMB2LE's GitHub page and click:
Settings → Developer settings → GitHub Apps → New GitHub App
Configure the following properties :
Name: gamb2le-mkdocs-builder (must be globally unique on GitHub) Homepage URL: https://github.com/GAMB2LE/ Webhook: uncheck "Active" — you don't need it
Then move onto permissoins, you must have:
Permissions → Repository permissions:
Contents: Read/Write
Actions: Read/Write
Everything else: No access
Where can this app be installed: "Only on this account"
All done, click Create GitHub App. Now you need to generate the keys that the builder can use to access the repos. On the next page, note the App ID (a number near the top). Scroll down to Private keys → Generate a private key. A .pem file will download.
Now you have to actually install the App on your repos. From the App's settings page, click Install App in the left sidebar. Select your org.Choose "All repositories" (since we want to document everything). Then click Install.
Finally, store the credentials. Go to mkdocs-portal repo → Settings → Secrets and variables → Actions and create two secrets:
APP_ID: the App ID number from step 5 APP_PRIVATE_KEY: open the .pem file in a text editor and paste the entire contents (including the -----BEGIN RSA PRIVATE KEY----- lines)
Local dev (see the page on your laptop while you edit it):¶
You need to simulate what the github actions do (clone the repos and update them) and then run a webserver, that looks like: