Nightly documentation

[DanielVoogsgerd]

Right now, this documentation functions as the basis for the stable version of Brane (I think). However, as we update Brane, it might be nice to have some documentation on features that have been merged, but not released yet. I suggest that, like the rust book, we add a nightly version of the docs as well.

So, my suggestion:

Compile the latest commits documentation to the directories: nightly/{user-guide,specification,docs}

Compile the latest versioned tag version to: ${latest_version}/{user-guide,specification,docs}

Symlink /stable to ${latest_version}
Symlink /{user-guide,specification,docs} to stable/${user-guide,specification,docs}

We could expand this to compiling all tags (with some filter like latest for each major) to their respective directory, this would make the /${version}/... URLs function like a sort of permalinks.

So a shortlist of features this would provide.

• Documentation on features that have not landed in a release yet
• Ability to easily correct mistakes in old docs
• Permalinks to documentation for (older) versions of Brane.

[Lut99]

OK, that would be hecking amazing if you could get that to work!

Is it even possible to version the docs? I.e., create releases for the docs in tandem with Brane's and then have paths like v1.0.0/... and such? No need to do it for older version, just for future ones.

Just be aware that this may need changes to links in the docs. I'm not sure how relative links are working, but with them recently becoming so it may mean that site-url has to be changed in book.toml in order for the links to point to the correct sub-path. But again I'm always confused what the rules are for markdown per server.

+1!

[DanielVoogsgerd]

OK, that would be hecking amazing if you could get that to work!

Is it even possible to version the docs? I.e., create releases for the docs in tandem with Brane's and then have paths like v1.0.0/... and such? No need to do it for older version, just for future ones.

Yeah, why not, we just have to create refs to versions of the documentation, and during CD the runner can just iterate over these tags and deploy them as well. These refs can either be tags for something on the static side, or branches if you prefer to update them more often, I suppose. I will get started now with a "nightly" and a "stable".

Just be aware that this may need changes to links in the docs. I'm not sure how relative links are working, but with them recently becoming so it may mean that site-url has to be changed in book.toml in order for the links to point to the correct sub-path. But again I'm always confused what the rules are for markdown per server.

We should, but luckily enough it fails quite gracefully if we mess it up, as this would make it backward compatible with any current references:

Symlink /{user-guide,specification,docs} to stable/${user-guide,specification,docs}

[DanielVoogsgerd]

Okay, progress update. This is mostly working. It isn't perfect, but I think it works. However, considering our last major release doesn't compile anymore. The openssl commit 96b1ce4 has to be backported to the tag v3.0.0, and maybe some other fixes we added since then. Maybe it is nice to create a v3.0.1 release for that.

Each version you want to publish in the docs has to be manually added to the CD, but with some matrix magic that has been reduced to a couple fairly small references:

At the top we have to specify the name of the stable release:

env:
  STABLE_RELEASE: v3.x.x

Then we have to instruct CD to build that version, which can be done by adding an entry to the matrix as shown below:

[...]
  # Build job
  build:
    strategy:
      matrix:
        include:
          - name: v3.x.x
            brane-ref: "v3.0.0"
            docs-ref: "main"

          - name: nightly
            brane-ref: "main"
            docs-ref: "nightly"
[...]

and finally, we have to collect the files into the right place in order for CD to be able to publish it like so:

      - name: Download docs (v3.x.x)
        uses: actions/download-artifact@v4
        with:
          name: docs-v3.x.x
          path: output/v3.x.x

      - name: Download docs (nightly)
        uses: actions/download-artifact@v4
        with:
          name: docs-nightly
          path: output/nightly

From that point on, we can just let CD take care of it. Maybe we can combine the second and the third section at some point, but I don't think doing so is worth the effort.

@Lut99, could you maybe:

• Create a v3.0.1 release tag that compiles 😅 (EDIT: I don't need an entire release, just a tag for which the docs compile)
• Create a ref on the brane-documentation repo that represents the stable (v3.x.x.) documentation?

If that is done, I think I can get a PR ready.

[Lut99]

Oh I see what you mean by ref. That's new to me!

Anyway ~ the last compiling version is epi-project/brane@96b1ce4, which already essentially integrates the policy reasoner. I doubt that the current version faithfully documents it, let alone any version that would've aimed 3.0.0...

So maybe let's not do 3.0.0. I'll tag the current (building) version as v4.0.0-test, then you can just use the most recent version of the docs. Does that work?