Convert CKAN Sphinx docs into admin/reference manual

[annapowellsmith]

As part of the general documentation overhaul (ticket:1142) we (APS and RGRP) want to convert the current Sphinx docs into:

• An Admin Manual which is task-based and aims to cover everything a developer would need to know to set up and customize a CKAN install.
• A Reference Manual which is the primary source of reference for CKAN software - this includes API docs.

The current chapters of the Sphinx docs should be moved as follows:

• index.rst - copy some stuff from README.txt, keep short
• README.txt - split out installation - stop symlinking in, keep separate, write new intro in index.rst
• [NEW] install.rst - new file on installation
• [NEW] theming.rst - move over from wiki
• api - will stay (gradually move tutorials/getting started to wiki.ckan.net user guide)
• i18n.rst: internationlization. say we have x langauges. just set lang config option. if your lang not there yet see wiki page for how to prepare a translation file
• design.rst - REMOVE (can copy some over if you can be bothered to ​http://wiki.ckan.net/Vision (all philosophical stuff should go!))
• loaders.rst: move to wiki.ckan.net/Using_Loaders
• feeds.rst: move to User Manual (CKAN_Feeds or just Feeds)
• importer.rst: remove (don't even copy)
• forms.rst: remove (ping david read and ckan-dev asking for replacement documentation -- do we need this in core ckan -- do we want pure js ...?). Suggest we start with (stub out) ​http://wiki.ckan.net/Customizing_Forms
• forms-integration.rst: remove
• model.rst: leave but move to reference (only for core devs)
• load-testing.rst -> move to ​http://wiki.ckan.net/Load_Testing
• distributed.rst -> remove
• admin.html should consolidate with authorization.html (some of authorization.html is probably in ref section but howto in main manual) <-- high priority
• deb.html -> go into reference (query james gardner on list about moving this to wiki?)

[dread]

I really think forms are a key asset of CKAN, and keeping the docs about customising and integrating them is important - i.e. forms.rst and forms-integration.rst. There are ideas being suggested for replacing bits of front-end, but forms hard to do, and David's new system is a significant offering on top of the CKAN back-end, so it seems crazy to me to abandon it.

forms.rst has been updated by David Raznick in the release_v1.4.1 branch.

i18n.rst - include here the creation of the pot file, deploying a translation, transifex admin

load-testing.rst - I think performance should be mentioned in the glossy guide (some sort of basic metrics of speed profile, to return web pages, run searches and API operations, for 100 or 1000 packages, on a given spec machine) and have it based on a report showing how we measured it. The report would look a bit like this file, and it might do as a stub, but it seems pretty lacking.

distributed.rst - agreed, remove.

design.rst - agreed, delete.

loaders.rst / loader_scripts.rst - yes move to wiki

feeds.rst - this should be split into a tutorial for the wiki and the reference page left in sphinx

importer.rst - this should be moved to ckanext-importer/doc

admin.html - this has already gone in 1.4.1

authorization.rst - This is a bit jumbled. We're talking about changes to the code, so maybe not worth working hard to make this good, so I suggest leaving it, but delete the boring section "Requirements and Use Cases".

deb.rst - this is an administrator task, so should stay why move this to the wiki?

buildbot.rst - ok to stay here?

vm.rst - I assume there's no problem with this

[thejimmyg]

This is now a child ticket of #1142

[rgrp]

Marking this as closed as Anna has completed and this is now deployed at ​http://docs.ckan.org/.