I’ve started using Documenter.jl to build up documentation for a (non-public) package I maintain. Because of the somewhat limited tools available to me and my team, I think I’ve come to the conclusion that the best way to allow users to access the docs is to keep them in the repository itself as markdown files (similar to what HDF5.jl does does.
I’m trying to figure out the best workflow for keeping the docs up to date, though. I have CI set up on our local Gitlab server for testing, and it would be nice to have that process also build/update the docs, but if the resulting markdown files are to be kept in the repo itself, I’m not sure there’s a way to do it that way.
Am I limited to just manually building the docs each time they’re updated and committing the new markdown files to the repository? Or is there a better way?
If I understand correctly, then you have the usual Documenter workflow. You can run Documenter automatically after the tests and have the CI deploy the built docs somewhere. For more details, see Hosting Documetation in Documenter’s manual. The environment variables that control deplydocs are documented in its docstring.
The only thing is that Documenter is quite GitHub & Travis-specific at the moment, but it should not be too hard to work around that. You just need to use e.g. GitLab Pages instead and set up the “Travis” environment variables yourself in the CI config.
I am curious to hear about what your experiences are with setting up Documenter on GitLab. I would actually like to generalize Documenter’s API a bit to make it more straightforward to use it on other Git hosting & CI services (e.g. GitLab, Bitbucket).
Thanks for your reply. Indeed, Gitlab Pages would probably be the way to go for me, but it’s not configured on our Gitlab instance (and that isn’t likely to change). My current proposed workaround is to keep the generated markdown files (from DocumenterMarkdown) in the repository (since Gitlab will render them), then just link to them from the README or something.
In general, my experience setting up Documenter on Gitlab was positive, with most of the hangups being on the Gitlab side rather than the Documenter configuration side. I primarily used @Tamas_Papp’s (very helpful) GitlabJuliaDemo.jl as a guide.
I have updated GitlabJuliaDemo.jl recently to 1.x and project-based Documenter workflow, if you find something is not working/missing please open an issue there.