I found this page on Github. It uses reStructuredText and demonstrates
how Github would render various elements out of the box. Of course, it
can be made more visually appealing with other tools, but it's a free
benefit that it renders on Github.
https://gist.github.com/ionelmc/e876b73e2001acd2140f
------ Original Message ------
From: "Lukas Tribus" <li...@ltri.eu>
To: "Nick Ramirez" <nrami...@haproxy.com>
Cc: "haproxy@formilux.org" <haproxy@formilux.org>; "Cyril"
<cyril.bo...@free.fr>
Sent: 7/1/2019 6:49:50 PM
Subject: Re: The case for changing the documentation syntax
Hello Nick,
On Mon, 1 Jul 2019 at 17:02, Nick Ramirez <nrami...@haproxy.com> wrote:
Hello all,
I'd like to propose something radical, but that will greatly help us in terms
of documentation. (And documentation is very important when it comes to people
choosing whether to use a piece of software, as I am sure you agree!)
First, the problem: Our documentation at
https://github.com/haproxy/haproxy/blob/master/doc/configuration.txt is written
using a sort of home-grown syntax that uses various conventions for indicating
sections, keywords, etc.
However, parsing this home-grown documentation is difficult. For example, I
contribute to the HAProxy Syntax Support for Atom project
(https://github.com/abulimov/atom-language-haproxy). This is a python program
that must parse the HAProxy configuration.txt file and find the keywords by
first finding specific section titles, then looking for lines that don't have
spaces in front of them. That's how we find the keywords in each section. It
must be updated when new versions of HAProxy are released because new sections
are added and the section numbers may change, and some sections are not
reliably using the home-grown syntax. In short, parsing configuration.txt is
difficult, error-prone and requires regular maintenance because its syntax is:
* Not a standard
* Not used consistently throughout the document
* Not easily parsed by existing tools (home-grown tools must be created and
maintained)
You may wonder, why do we need to parse configuration.txt? The reasons are:
* A text file without any styling is difficult to read, so we want to add
styling (e.g. convert it to HTML with CSS or offer a PDF download)
* We want search functionality of the document and an auto-generated table of
contents
* We want to write haproxy.cfg files and have them displayed in
syntax-highlighted color when using Github Gist or any modern text editor
(Atom, VS Code, Sublime Text, etc.). For that, we must currently parse
configuration.txt to learn the keywords (as in the atom-language-haproxy
project mentioned). For example, we use Github Gist, with the
atom-language-haproxy project, to display HAProxy configuration snippets in
color on the haproxy.com/blog. It would be easier to maintain this if we could
parse configuration.text more easily.
Actually since 7 years we do 2 of the 3 things you mention here;
documentation.txt and others are parsed automatically (in python) and
generate a verify nice HTML site, searchable and indexed with table of
contents, etc:
https://www.mail-archive.com/haproxy@formilux.org/msg07040.html
https://github.com/cbonte/haproxy-dconv
https://cbonte.github.io/haproxy-dconv/
We use this extensively and are able to point people to specific
sections or keywords of the documentation. When the documentation is
inconsistent and breaks the tool, we (or more specifically Cyril)
fixes it. I don't see any 2.0 specific changes in haproxy-dconv, and
I'm not sure if a structured text would fix all the issues you have
with the atom project.
I'm not saying we should maintain configuration.txt as it currently
is, but to me the status-quo does not feel as dire as you suggested.
haproxy-dconv also mentions:
The purpose of this project is to ultimately convert the HAProxy documentation
into a more generic format (example : ReStructuredText) that would allow for an
easier spreading of various output files (.pdf, .html, .epub, etc).
So it seems like there is common ground. I'm CCing Cyril who has
invested a lot of time for this already.
I think I agree that we would benefit from moving towards a
standardized, structured text.
Regarding markdown vs reStructuredText vs asciidoc, I don't have a lot
of experience with either of those, but if we go down this road I feel
like we should pick a format that is here to stay and is standardized,
and for me, that is reStructuredText. Markdown is probably the worst
possible choice and I know first hand how the lack of standardization
negatively affects it's interoperability (specifically a site had a JS
based preview that looked different than when the server-side code
parsed it after the submission ... so I have a strong negative opinion
about Markdown).
Readthedocs supports reStructuredText (and discourages but supports
markdown), however asciidoc is not supported. Not that we need to use
readthedocs, but it's something to keep in mind.
cheers,
lukas
