Support autosorting a TOC

[shimizukawa]

Background: saltstack/salt#10799

Proposal: support :sort: option to toctree which will sort all top level elements(' titles) in the toctree according to alphabetical order.

---

• Bitbucket: https://bitbucket.org/birkenfeld/sphinx/issue/1430
• Originally reported by: Jens Rantil
• Originally created at: 2014-03-22T23:27:14.365

[tk0miya]

+1: Reasonable. It would be nice if we can support this. But it is difficult to implement.

• Reading phase
  • reST parser parses the document and invoke toctree directive if found.
  • toctree directive parses its contents and build toctree node.
  • At this moment, we can't sort toctree entries by title because reading processes run parallelly. So there are no way to obtain titles info from other processes.
  • After reading one document, Sphinx stores the toctree info to the environment object (still not sorted).
• Writing phase
  • At this moment, we can sort toctree entries by title.
  • But we also need to update toctree info on the environment object.
  • Additionally, there are no good event to do that...

[shimizukawa]

But it is difficult to implement.

I think so too.

[AA-Turner]

This can be achieved via :glob:, which inserts pages alphabetically.

A