Deploying generated documents privately

question
#1

I am working on a project using Julia which will eventually be made public & open source. We are currently working using a private repo Gitlab, and are in the process of writing up docs — this helps coauthors and should be useful for future readers, too.

I am wondering how (& where) I could deploy docs generated with Documenter.jl once CI passes with restricted/authenticated access. Concrete workflow suggestions would be nice, but I would also find general suggestions and tools helpful and figure out the rest. It should be free, at least for academic use. My fallback is uploading from the Docker image to Dropbox via the latter’s command line integration.

6 Likes
#2

Doesn’t Documenter.jl’s make.jl create static html? You could just deploy it on gitlab pages.

#3

I’ve been wondering about this too. One idea I have is to deploy the Markdown output to GitLab Wiki which manages pages in Git. I guess setting up CI to push to the wiki is relatively easy (see https://docs.gitlab.com/ee/ci/ssh_keys/README.html). A trickier part is that Julia and Documenter.jl are not as CommonMark-compatible as GitLab. (Documenter.jl has been (and is) targeting mkdocs which interpret the input as the original Markdown and not CommonMark.) I haven’t tried this idea yet so I don’t know how troublesome it is, though.

1 Like
#4

AFAIK Gitlab pages are public even for private repos.

#5

Good point. I like @tkf 's solution. Didn’t know gitlab’s wiki is just a git repo. Not sure how hard it is to setup the CI to deploy to it though.

A compromise could be to have the CI just run docs/make.jl and deploy markdown output to a branch like it does when set up for github pages (gh-pages). Then simply give your users a link to this branch in the repo (not the wiki), and rely on gitlab to render the md files.

#6

I set up a repo building Julia docs at our private gitlab server, hosting it on the servers gh-pages. It worked with some manual tweaking of some scripts etc. I’ll see if we can get the repo changed to public so that I can share a link, the mkdocs and yml files might be useful for you.

#7

A private Gitlab server is actually something I have been considering for a while, for multiple reasons. It would solve many problems (and create wonderful new ones :wink:).

1 Like