Add table of contents to each multi-page documentation page, including examples


(Danny Thomas) #1

The Gradle documentation is fantastic, but I fInd it difficult to navigate with only a single table of contents. If each multi-page documentation topic displayed a full TOC in place, including sections and examples, it’d make it a lot easier to get around.

If it were pinned to the top and right, and collapsible, it’d mean you wouldn’t need to jump to the top of the page too…


(Luke Daley) #2

Hi Danny,

Can you point to an example of what you’re envisioning?


(Danny Thomas) #3

The Django docs are a good example: Contents for the current topic, plus the ‘Browse’ section lets you jump to the ToC and it and the ‘You are here’ secion keeps you oriented to where you are in the documentation: https://docs.djangoproject.com/en/1.5/ref/validators/.

Their side bar scrolls with the rest of the document though, so you have to return to the top of the page to refer to it. It might work better if it was fixed like the Gradle documentation top bar, but could be collapsed to expand the readable area, i.e. like the Python docs here (but think it works better on the RHS), keep the top bar and side bar content visible - http://docs.python.org/2/library/. I also like that the Python docs give you a drop down to get to previous versions of the documentation.


(Luke Daley) #4

We plan to overhaul the doc generation, hopefully later in the year. It’s not a trivial undertaking unfortunately.

I’ve raised GRADLE-2857 to track this particular idea.

Thanks.