Find inspiration in graphs to format the index

[David Lucas]

While looking at the documentation, I found the index file for graphs. It seems nice, and very clean and ordered (I think they did well to sort algorithms). It could be a good example on what to do with the index file of coding when it will grow (a lot of encoders/decoders plus channels will require clean sorting to be readable).

See here.

[Johan Rosenkilde]

What file?

[David Lucas]

The index.rst file, which is used to create the index.html file that you see when you click the link I provided in the first message.

It's the file you have in every folder of the reference manual (see src/doc/en/reference/myfolder/index.rst).

I was just saying that our index of files in coding is messy, while graphs is quite ordered and easy to read.

It's an idea coming from a discussion we had with Vincent on 18269, in which we said that ordering will be necessary when channels_catalog and channel_constructions and encoders/decoders will be in the index. Otherwise, it will look terrible. And I just thought that this index file for graphs is quite nice.

[Johan Rosenkilde]

Ok, sorry, didn't see the "See here" line :-)

[Johan Rosenkilde]

I completely agree. We were touching upon this as well at the discussion in Lyon. I agree that Graphs seems to be exemplarily structured in this part of the documentation. And no half-baked math-explanations about what a graph is at the top ;-)

[David Lucas]

No problem.

And if you look inside the documentation itself, like in graph colouring for instance, you see that the file itself is really well structured, and pleasant to read.

This kind of presentation could be used in channel_constructions as we planned that it will be quite heavy, so using an index like they did at the head of the file would be a real plus.

[Johan Rosenkilde]

You did this?

[David Lucas]

Done in trac #19907