[llvm-commits] Refactor Sphinx homepage

Bill Wendling wendling at apple.com
Thu Jun 21 01:32:36 PDT 2012


On Jun 9, 2012, at 12:49 AM, Sean Silva wrote:

> This is a first step towards structuring the Sphinx docs better to make them easier to browse and use. It doesn't change the structure or contents of the docs at all.
> 
> In a future patch, I'm planning on taking each of
> 
>    design_and_overview.rst
>    userguides.rst
>    programming.rst
>    subsystems.rst
>    development_process.rst
>    mailing_lists.rst
> 
> and reintegrating them into the homepage. This will be similar to how the old html docs homepage was, so it will be familiar (and super-fast to search with Ctrl-f, which I've seen at least one other person miss). The current setup is just really bulky and hard to navigate, being on different pages, when there's really not that much there, certainly not enough to merit splitting up.
> 
> Another thing, but an important one, is that the way the current docs are laid out in the reST source makes the end result incredibly ugly. For example, the lists are indented by a space or two in the .rst file, which causes Sphinx to emit a list of indented bullets, even though the bullets are logically at the top level. Also, semantically, they should be definition lists, not bulleted lists.
> 
> I'll be fixing all of these things once I get my feet wet with this patch.
> 
> Feedback on which direction to take the docs after that would be appreciated.
> 
I like the direction you're going in. I too think that the separation into different reST documents is harder to navigate (and I use ^-f myself).

One comment on your patch: For the "note", you can format it with the ".. note::" tag to put it in a pretty little box.

-bw





More information about the llvm-commits mailing list