[ckan-dev] Documentation rearrangement

Fri Apr 12 15:03:44 UTC 2013

Hey all, I'd like to rearrange the docs quite significantly for 2.0, but
I thought I'd better check first in case anyone has their own ideas or
just thinks mine are crazy.

My problems with the current layout are:

Section titles within the main table of contents, so if I want to send
someone a link to "the ckan api" it has to be
docs.ckan.org/en/latest/index.html#the-ckan-api rather than
docs.ckan.org/en/latest/api.html. Also there's nowhere to put any
general introductory text about the ckan api, unless I put it in the
middle of the table of contents, or add a new 'introduction to the api'
page.

Some of these top-level section titles are not very good. For example,
Customizing and Extending contains things like how to use the Apps &
Ideas or the Email Notifications features. These don't fit very well
under "Customizing and Extending" imho. "Publishing Datasets" mostly
contains nonsense. "General Administration" could refer to the entire
documentation. "Other Material" contains only the changelog!

What I'd like to do is copy how it's done in the Python Library
Reference:

http://docs.python.org/2/library/

There's a Show Source link in the sidebar of each page of those docs so
you can see how it's done in Sphinx.

My plan:

Delete the section titles from the index.rst file. index.rst will just
contain one big toc-tree that sources all of the content files. We can
also add a couple of general introductory paragraphs at the top, like
the python docs have.

This means that the top-level sections we currently have will get
"flattened out" and disappear. Mostly I think this is good, a simpler
flatter structure will be easier to deal with, especially for devs when
trying to figure out where to add the docs for their new feature.

But some of the current top-level sections we really want to keep. For
example, I would probably move the six pages currently under
"Installation" into one installation.html page. Also the four pages
currently under "The CKAN API" into one api.html page. "For CKAN
Developers" as well.

Some of these new combined pages may be very long. In that case, the page
should have its own table of contents and break itself up into sub
pages. For example, if you click on "7. String Services" in the python
docs it takes you here:

http://docs.python.org/2/library/strings.html

A page with some general introductory text and then a table of contents
where all the gory details are broken down into sub-pages.

One other thing: the sidebar shows the table of contents for the current
page only, but _not_ if the current page is already a page with a toc on
it!

They also have a "Report a Bug" link in the sidebar, maybe a good idea.

This will mean that any links out there in the wild linking to pages
within our docs, are likely to get broken (at least, they will if they
link to latest, links directly to 1.8 or 1.7 etc will be fine)