Adding structural section numbers to docs.

[stenskjaer]

A suggestion from one of our illustrious users: adding numbers (1. / 1.1 / 1.2 / 2. / 2.1 etc) to titles and subtitles would make the structure of the document easier to follow. This is of course a matter of taste, but when I was looking at the instructions for the first time, it was quite difficult for me to see from the formatting alone to which level each new title belongs.

The suggestion was made by Juhana Toivanen.

I'm don't have strong opinions about this, but I see how it could be a nice advantage. Would also make it possible to refer to the docs by §'s.

[jeffreycwitt]

I think i'm in favor of this. But ideally, we should be able let the computer calculate this and display this numbering using css.

What makes this complicated is difficult Markdown renderers do different things. Pandoc will use the headers to created nested divs for each sections. I'm pretty sure the github markdown renderer does not. Thus, you have a bunch of headers in one div.

All that to say, I would prefer to automate this rather than hard coded. But practically speaking maybe that is more trouble than its worth and we should just hard code them.

[stenskjaer]

I agree that automatization would be a lot better. A possibility might be to switch (maybe down the road) to https://www.gitbook.com/. I'm pretty sure that is possible with that setup.

Edit: I also looked at the possibility of section numbering in readthedocs.org, but I couldn't spot it at a quick glance through their docs.

[jeffreycwitt]

agreed. good topic for our 1.1/2.0 meeting