Automate releasing documentation

[mniewrzal]

Would be nice to automatically generate/deploy a new version of documentation after each release.

[mniewrzal]

@Erikvv could you add more details how we can do this?

[Erikvv]

High level:

• Make sure jenkins builds the latest tag when tagging, doesn't seem like it currently does anything with tags.
• Set the tag in

  uplink-c/docs/Doxyfile

  Line 41 in 12b6f40

  PROJECT_NUMBER = v1.5.1

  (for CI replace with environment variable)
• run ./docs/generate.sh
• commit and push the branch gh-pages from directory ./docs/gh-pages

Note: we currently only host documentation for one tag, which would have to be the latest. I was looking at processing the Doxygen XML output with Breath+Sphinx to support this and maybe other improvements.

[egonelbre]

Note, it might be easier to do with github actions.

You can setup a github action something like:

name: Generate Docs
on:
  push:
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2

      // -- install tools --
      // -- generate docs --

      - name: Publish
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./public
          force_orphan: true

Adjust the publish_dir as needed.

[egonelbre]

Also, I think ideally we would want to generate the docs for all versions.

But, in general, since the docs are minimal here, I would stuff together a golang templates rather than creating a huge documentation pipeline.

[Erikvv]

egon:
I would stuff together a golang templates

What do you mean by this?

[egonelbre]

Rather than requiring Doxygen + other stuff, it shouldn't be too difficult to put together html/template + use a C header parser to generate a docs page. Or use Go ast and syntax analysis directly to figure out the C data-structures. Might be a fun innovation time project.

But, using Doxygen is also completely fine.

[Erikvv]

So to scope the issue:

• my instructions in Automate releasing documentation #12 (comment)
• make a trigger for github actions (manual button or after creating tag)

[Erikvv]

I tried out the Doxygen+Breathe+Sphinx pipeline to generate better docs for Uplink-C than pure Doxygen. I didn't want to start on this issue before investigating this.

My conclusion is that these are good tools when you want to put effort to write very good documentation like on readthedocs.io and still be able to reference structs and functions in the code, but it is a regression in terms of automatic generation of API docs. If anyone wants to put in the effort I can certainly recommend it, I have a branch saved.

So I should just do what I described before to automate Doxygen.