Automate deployment of documentation

[demeringo]

Problem

It seems that changes in documentation are not automatically reflected on http://api.boavizta.org/.

Solution

Automate the republish of documentation after a merge to main branch. Maybe add a github action to handle it.

[demeringo]

@da-ekchajzer do you know how the doc is deployed today ? Is it a manual process ?

[da-ekchajzer]

It is indeed a manual process. Each release (not commit) build a docker image for documentation which is manually pull on the server.

What do you suggest to by more automatic ? Documentation should be updated for each commit ?

For now, I'll make a manual build on a local repo and push it to the server. It's a very annoying process :).

[demeringo]

Yes, the central question is more "when do we want to publish a release", and if the release of code and doc should be (or not) synchronized.

I tend to think that doc update cycle could be differents (for example no need to wait for a release to fix a typo or add a tutorial). However, in some cases, we still need sync (if we describe a new feature, not yet released).

Also I believe that once we open-source the code, it could simplify the doc publishing infra (we could use public github pages or other cheap hosting).

[da-ekchajzer]

To fulfill both cases, we could have :

• the dockerised documentation publish on release and tagged with the release number.
• The always up-to-date documentation linked to our GitHub page

[da-ekchajzer]

We need the repo to be public to release a github page. I put the workflow here, waiting for the opening of the repo.

name: Publish docs via GitHub Pages
on:
  push:
    branches:
      - main

jobs:
  build:
    name: Deploy docs
    runs-on: ubuntu-latest
    steps:
      - name: Checkout main
        uses: actions/checkout@v2

      - name: Deploy docs
        uses: mhausenblas/mkdocs-deploy-gh-pages@master
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          CUSTOM_DOMAIN: api.boavizta.org
          CONFIG_FILE: docs/mkdocs.yml
          EXTRA_PACKAGES: build-base
          REQUIREMENTS: docs/requirements.txt

docs/requirement.txt

mkdocs-material ~= 8.1
mkdocs-render-swagger-plugin == 0.0.3

[demeringo]

Hi @da-ekchajzer, now that the repo is public, we may relaunch this.

• Is api.boavizta.org already pointing to github pages ?

[da-ekchajzer]

Hi,

api.boavizta.org is linked to a development server.

We could work on it now that the repo is public !

There is some work on CI/CD Wich I am not so familiar with. I will put the issue in "Help wanted"

[da-ekchajzer]

Should we deploy to GitHub pages the documentation only or also the API endpoint ? We should deploy the doc "on push" on main branch and work on dev branch on the version in progress.

[demeringo]

@da-ekchajzer, yes I believe that we should deploy the documentation as a set of github pages, at least for the main branch.

We could use something similar to what is done in cloud scanner with github actions. https://github.com/Boavizta/cloud-scanner/blob/24600cb77eea68740e759f1e9d1ce79f87f72e84/.github/workflows/publish-doc-to-github-pages.yml

• The doc publishing framework is slightly different (mdbook used for cloud scanner vs mkdocs for the API). We should be able to reuse most of the action. So we need to use some flavor of mkdocs build command to generate the static set of pages.
• the key thing in this action is the git worktree add gh-pages command that allow to checkout a different branch (gh-pages) of the repo along wth the main branch. We generate on the main branch but commit result on gh-pages branch.
• We need to ensure that mkdoc plugins work in this context (see docs/requirement.txt)
• an additional configuration is needed on the repo itself (under /settings/pages) to activate repo-related github pages and indicate which branch of the repo contains generated github pages (gh-pages in the example action). Just ignore Jekyll related information as we do not use it here.
• Afterwards, we also need to update the readme or other OpenAPI/Swagger doc pointing to the documentation URL.

[da-ekchajzer]

Done ! Documentation is avaible at : https://doc.api.boavizta.org/