Mirror of forum.nim-lang.org

10616 :: Github action to build documentation

• amadan (orginal) [2023-11-09T02:20:42+01:00] view original

  I made a Github action to make all my docs building be done in CI and thought I'd share it in case anyone is interested

  https://github.com/ire4ever1190/nim-docs-action

  Can be added to an existing workflow by adding this step (Full working example is in the repo's readme)

  - name: "Build documentation"
    uses: "ire4ever1190/nim-docs-action@v1"
    with:
      main-file: src/foo.nim # Replace with your main file
      # deploy: pages # If you want to auto-deploy to Github pages also
  Run

  One difference compared to other solutions I've seen is that this builds documentation for the latest tag, that way the documentation lines up with what someone would usually install (Working on building both stable/devel docs).

  Feedback/criticism is welcome!

---

• Isofruit (orginal) [2023-11-09T08:19:19+01:00] view original

  Sweet! I documented workflow files in my "NimSetup" repository (just my obsidian md files regarding various boring technical stuff such as setting up workflows).

  Generally in terms of feature feedback I'd have the following desires:

  • Is it possible to have the action do builds in a way that it doesn't overwrite previous builds? As in, that you build always the latest tags but what you serve via github pages is all APIs of all versions. That way in the README.md I could have e.g. links to the nimble docs of each release of my package
  • Is it possible to specify the nim-version with which these docs are built?
  • Unrelated to the docs task, would it be interesting for you to also write a workflow the executes the nimble test command together with an array of nim version for which to execute them?

---

• amadan (orginal) [2023-11-10T01:27:07+01:00] view original

  Very possible and something I want to do. My two current ideas are

  • Using action cache: This is the least hacky method, but since the archives expire it means you'd need to do a full documentation rebuild if you come back to a project after a while.
  • Store a compressed version of the site where its getting hosted: That way it can download the old version and add in the new version. This idea seems kinda hacky though.

  I'd need to look into it more, cause a full docs rebuild might not be too slow

  The action doesn't configure Nim, you need to do it yourself (Which means you can choose any Nim version). I did this so people aren't restricted to how I'd configure Nim.

  Definitely want to do that, also aim to emit .idx files for it so it shows up in the index (Like with the Nim documents)

  Would certainly be possible, though the main configuration would be making the matrix which you'd need to do even if there was an action for it so it wouldn't save much configuration

---