Documentation improvements

[Tiago Rodrigues]

Hi everyone,

while doing some improvements to the AMD docs this weekend I thought a bit about some improvements that could be made to the documentation, but I'd just like to get some opinions on this before diving in.

First of all, I think the table of contents on the homepage is a bit confusing and misleading, mostly due to the overview section having so many sub items. As I understood it, that TOC is generated by Sphinx automatically anyway.

I think it would be helpful to develop some of those overview sections into more elaborated pages under the other sections, and keep each section in the overview smaller, and with links to these other pages. This would also help avoid duplication of content.

Before the Sphinx generated website there used to be an assertions/expectations list on the sidebar which was very handy and helpful. I think it would be great to try and bring that back.

We should probably also go through some of the things marked as experimental/not implemented and update those.

Well, that's mostly it. Let me know what you think, because I'm really keen to help out with this stuff, and hopefully find some more time to try and dive in to some actual code and development :)

[Christian Johansen]

Hi,

> while doing some improvements to the AMD docs this weekend I thought a bit
> about some improvements that could be made to the documentation, but I'd
> just like to get some opinions on this before diving in.
>
> First of all, I think the table of contents on the homepage is a bit
> confusing and misleading, mostly due to the overview section having so many
> sub items. As I understood it, that TOC is generated by Sphinx
> automatically anyway.

It is. Unfortunately I'm still not pro enough with Sphinx to know what
are options are for tweaking this is, but maybe someone who do knows
Sphinx can pitch in? Jodal? :)

If there's no way to tweak it, at least we could use JavaScript to
collapse certain parts of it?

> I think it would be helpful to develop some of those overview sections into
> more elaborated pages under the other sections, and keep each section in
> the overview smaller, and with links to these other pages. This would also
> help avoid duplication of content.

Agree.

> Before the Sphinx generated website there used to be an
> assertions/expectations list on the sidebar which was very handy and
> helpful. I think it would be great to try and bring that back.

The list of assertions was useful indeed. I know that Daniel Wittner has
added back a quick list over assertions in his PR:
https://github.com/busterjs/buster-docs/pull/12

I haven't gotten around to review it yet, but maybe that would solve
this problem?

> We should probably also go through some of the things marked as
> experimental/not implemented and update those.

Definitely.

> Well, that's mostly it. Let me know what you think, because I'm really keen
> to help out with this stuff, and hopefully find some more time to try and
> dive in to some actual code and development :)

Thanks Tiago, your help is most appreciated!

Christian

[Stein Magnus Jodal]

On Tue, Feb 19, 2013 at 7:50 AM, Christian Johansen
<chri...@cjohansen.no> wrote:
>> First of all, I think the table of contents on the homepage is a bit
>> confusing and misleading, mostly due to the overview section having so many
>> sub items. As I understood it, that TOC is generated by Sphinx
>> automatically anyway.
>
> It is. Unfortunately I'm still not pro enough with Sphinx to know what
> are options are for tweaking this is, but maybe someone who do knows
> Sphinx can pitch in? Jodal? :)

The quick fix here is to reduce the depth of the ToC by changing the
:maxdepth: setting in the ToC markup from 2 to 1. Have a look at
https://raw.github.com/busterjs/buster-docs/develop/index.rst, and I
think you'll figure it out quickly :-)

If you want to have subpages for each main section of the site
("User's guide", "Reference documentation", "Project resources") with
deeper ToCs, you should:

1. create a userguide.rst file for the "User's guide" section,
2. move the ToC for the User's guide pages from index.rst to userguide.rst, and
3. add a new ToC in index.rst containing simply:

.. toctree::
:maxdepth: 2

userguide

A page cannot be included multiple places in the ToC, but the ToC
structure can be defined across multiple pages as long as the ToC
structure as a whole becomes a single tree structure. E.g. index.rst
can include userguide.rst in its ToC, while userguide.rst can include
the rest of the User's guide pages in its ToC.

Hope that makes any sense at all.

--
Stein Magnus Jodal