OPNsense Forum

English Forums => Documentation and Translation => Topic started by: Alphakilo on April 19, 2018, 05:18:55 pm

Title: Dockerized "buildsys" for the docs (Sphinx)
Post by: Alphakilo on April 19, 2018, 05:18:55 pm

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]

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

Title: Re: Dockerized "buildsys" for the docs (Sphinx)
Post by: franco on April 20, 2018, 01:33:50 pm

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

Title: Re: Dockerized "buildsys" for the docs (Sphinx)
Post by: Alphakilo on April 20, 2018, 06:22:13 pm

Quote from: franco on April 20, 2018, 01:33:50 pm

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

Title: Re: Dockerized "buildsys" for the docs (Sphinx)
Post by: fvanroie on May 03, 2018, 10:45:04 pm

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

Title: Re: Dockerized "buildsys" for the docs (Sphinx)
Post by: franco on May 04, 2018, 08:31:54 am

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