okfn/ckan — pull request #1322 by seanh (2013-11-15 11:45:05+00:00)
Title: [wip] Reorganize Solr setup docs

This is marked as wip because these docs still need to be tested on a fresh VM.

The Sphinx navigation for the Solr part of the source install docs is currently broken. The way the docs are currently supposed to be followed is:

1. You start following the source install docs from the top of the page down
2. When you hit the Solr setup part, you click the link to go to the Solr page, follow those docs, then go back to the source install page and continue with the next step

So the Solr setup page is a "sub-page" of the source install page. But afaik Sphinx doesn't support sub-pages, it only supports linearly ordered pages. So when you get to the bottom of the source install page, Sphinx's link to the "next page" sends you back to the Solr setup page which you've already done, and you go in circles. (Also the table of contents is broken on the Solr page.)

What I've done to fix this is:

1. Put the Solr setup docs inline in the Source install page

2. Remove the single core Solr setup docs, support only multi core. Otherwise the docs are non-linear and it's imho too long and difficult to follow which parts you should be doing and which not. (Also single-core is just not a good idea.)

3. Add new docs on a separate page for creating a second Solr core

I've given the instructions assuming CKAN has a single schema.xml file
(and not schema-1.4.xml, schema-2.0.xml, etc.) which I don't think is
correct at the moment, but I think we're changing to it.

If we're changing to a single schema.xml file, then the package and
source upgrade instructions that tell you to update your schema.xml
symlink can be deleted.

Also renamed the default Solr core and schema from ckan-schema-2.0 to
ckan_default. It's not one Solr core per CKAN schema, it's one Solr core
per CKAN instance, that makes more sense to me. (When you upgrade your CKAN instance to a new version of CKAN, potentially with a new schema, you'll keep using the same Solr core.)