Closed demeringo closed 1 year ago
@da-ekchajzer do you know how the doc is deployed today ? Is it a manual process ?
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 :).
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).
To fulfill both cases, we could have :
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
Hi @da-ekchajzer, now that the repo is public, we may relaunch this.
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"
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.
@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
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.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.docs/requirement.txt
)Done ! Documentation is avaible at : https://doc.api.boavizta.org/
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.