Dockerized "buildsys" for the docs (Sphinx)

[Alphakilo]

Heya!

So I wanted to give the documentation some love (sidenote: reStructuredText is an awful markup) but found myself unwilling to install Sphinx in order to get previews.
Then it hit me. This is what Docker was made for.

The result is this:
https://github.com/Alphakilo/opnsense-sphinx-doc-docker
https://hub.docker.com/r/alphakilo/opnsense-sphinx-doc/

Now instead messing around with python and its dependencies you can run

Code Select Expand

docker run --rm -v ~/src/docs:/docs alphakilo/opnsense-sphinx-doc:latest and enjoy your build.

I have a few questions about the "official" build process, since I couldn't find resources about that.
What version of Sphinx and Python is used to build for docs.opnsense.org?

I don't want nasty surprises regarding parsing or formatting that may be depending on the Sphinx version, or some stupid library.

Regards

[franco]

Hi Alphakilo,

I have this on my list to add to the tools.git a clean docs build documentation and tool-chain.

Actually I don't know the prerequisites, because I wasn't previously involved in the docs build process since it was only just open-sourced for 18.1.


Cheers,
Franco

[Alphakilo]

Actually I don't know the prerequisites, because I wasn't previously involved in the docs build process

I feel your pain  ;D
I just went for the latest stale stable Versions in the jessie repositories. Python 3.6 and Sphinx 1.7.2

[fvanroie]

This docker is a great tool. It worked for me on the first run and now I'm able to write & compile docs... I wouldn't know where to start building Sphinx from scratch, so I took this shortcut.

Next up is to figure out reStructuredText syntax.  :D

[franco]

Looks like almost all ports are available in FreeBSD. Their repo is acting up on blockdiag packages install at the moment, but I'll try to follow-up later to see if that is resolved.


Cheers,
Franco