Improve navigation & structure of documents

Presently, the new RTD contents list in the sidebar is more or less unusable:

https://www.dropbox.com/s/bl36v087cza6r7v/Screenshot%202014-07-14%2014.48.21.png (image)

The new version looks like:

https://www.dropbox.com/s/soiv9iq4vss1v9k/Screenshot%202014-07-14%2014.49.50.png

The expanded table of contents still appears in the main index page.

conf.py has also been updated to use the new RTD theme locally, if the user has it installed; if not
it will use the built-in theme as usual.

Also includes miscellaneous minor corrections.

docs/advanced/index.rst

@@ -0,0 +1,16 @@
+###############
+Advanced topics
+###############
+
+django CMS is extremely flexible and has a number of powerful features that you might not need to
+avail yourself of straight away.
+
+.. toctree::
+    :maxdepth: 2
+
+    i18n
+    caching
+    sitemap
+    templatetags
+    cli
+    permissions_reference

docs/basic_reference/index.rst

@@ -0,0 +1,15 @@
+#########################################
+Basic reference, configuration & guidance
+#########################################
+
+Once you have django CMS working, you'll want to explore its features and capabilities in more
+depth, and customise its behaviour to meet your needs. 
+
+.. toctree::
+    :maxdepth: 2
+
+    configuration
+    navigation
+    plugin_reference
+    using_south
+    ../faq/common_issues

docs/concepts/index.rst

@@ -0,0 +1,12 @@
+##########################
+Key concepts in django CMS
+##########################
+
+This section doesn't explain how to do anything, but explains and analyses some key concepts in django CMS.
+
+.. toctree::
+    :maxdepth: 2
+
+    menu_system
+    publishing
+    multiple_languages

docs/concepts/publishing.rst

@@ -1,6 +1,7 @@
 ##########
 Publishing
 ##########
+
 Each page in the CMS exists in two versions: public and draft. The staff users
 generally use the draft version to edit content and change settings for the
 pages. None of these changes are visible on the public site until the page is
@@ -13,15 +14,12 @@ automatically published once the parent page is published. This enables you to
 edit an entire subsection of the website and publishing it once all the work is
 complete.
 
+**************
 Code and Pages
---------------
+**************
 
 If you need to manipulate pages by code be sure to filter on ``publisher_is_draft=True``.
 This will give you only the draft versions of pages and this are the ones you actually see
 in the admin and in draft mode in the frontend. There is a publish signal fired
 every time a page is published. In this moment a second page is created and all titles,
 placeholders and plugins are copied to the public version.
-
-
-
-

docs/conf.py

@@ -109,9 +109,17 @@
 
 # -- Options for HTML output ---------------------------------------------------
 
+# on_rtd is whether we are on readthedocs.org
+on_rtd = os.environ.get('READTHEDOCS', None) == 'True'
+
+if not on_rtd:  # only import and set the theme if we're building docs locally
+    import sphinx_rtd_theme
+    html_theme = 'sphinx_rtd_theme'
+    html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
+
 # The theme to use for HTML and HTML Help pages.  Major themes that come with
 # Sphinx are currently 'default' and 'sphinxdoc'.
-html_theme = 'default'
+# html_theme = 'default'
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the

docs/contributing/index.rst

@@ -0,0 +1,17 @@
+#########################
+Development of django CMS
+#########################
+
+django CMS is an open-source project, and relies on its community of users to keep getting better.
+
+You don't need to be an expert developer to make a valuable contribution - all you need is a little
+knowledge of the system, and a willingness to follow the contribution guidelines.
+
+Remember that contributions to the documentation are highly prized, and key to the success of the
+django CMS project.
+
+.. toctree::
+    :maxdepth: 2
+
+    contributing
+    testing

docs/extending_cms/index.rst

@@ -0,0 +1,22 @@
+#################
+Extending the CMS
+#################
+
+django CMS is thoroughly extensible. Nearly all of its components can be not only configured and
+customised, but also extended to provide brand-new functionality through numerous hooks and stable
+APIs.
+
+.. toctree::
+    :maxdepth: 2
+
+    extending_examples
+    extending_page_title
+    custom_plugins
+    app_integration
+    api_references
+    placeholders
+    toolbar
+    frontend_models
+    searchdocs
+    fields
+    testing

docs/getting_started/installation/index.rst → docs/getting_started/index.rst

@@ -1,10 +1,17 @@
-#####################
-Installing django CMS
-#####################
+###############
+Getting started
+###############
+
+Welcome to django CMS 3. This tutorial should guide you  through the first basic steps with django
+CMS all the way up to adding your own plugins and apps and extending the CMS' models itself!
+
+.. toctree::
+    :maxdepth: 2
+    :hidden:
+
+    tutorial
+    integrate
 
-Welcome to django CMS 3. This tutorial should guide you 
-through the first basic steps with django CMS all the way up to adding
-your own plugins and apps and extending the CMS' models itself!
 
 
 ************
@@ -16,17 +23,21 @@ can get help from either our `mailinglist`_ or IRC channel ``#django-cms`` on
 the ``irc.freenode.net`` network.
 
 
+**********************************
+Installing django CMS from scratch
+**********************************
+
+Start from scratch by following the tutorial on https://github.com/divio/django-cms-tutorial
+
 **********************************************
 Installing django CMS into an existing project
 **********************************************
 
-You can integrate django CMS it into your existing django project: :doc:`integrate`
-
+.. toctree::
+    :maxdepth: 2
 
-**********************************
-Installing django CMS from scratch
-**********************************
+    integrate
 
-Or you can start from scratch by following the tutorial on https://github.com/divio/django-cms-tutorial
 
 .. _mailinglist: https://groups.google.com/forum/#!forum/django-cms
+

docs/getting_started/installation/integrate.rst → docs/getting_started/integrate.rst

@@ -4,7 +4,7 @@ Installing django CMS into an existing project
 
 
 This document assumes you are familiar with Python and Django. It should
-outline the steps necessary for you to follow the :doc:`../tutorial`.
+outline the steps necessary for you to follow the :doc:`tutorial`.
 
 .. _requirements:
 
@@ -220,7 +220,7 @@ or
 
 This will install Django, django CMS, South, Pillow, and your database's driver globally.
 
-You have now everything that is needed for you to follow the :doc:`../tutorial`.
+You have now everything that is needed for you to follow the :doc:`tutorial`.
 
 
 On Mac OSX
@@ -334,8 +334,9 @@ Also add any (or all) of the following plugins, depending on your needs::
     Adding the ``'djangocms_snippet'`` plugin is a potential security hazard.
     For more information, refer to `snippet_plugin`_.
 
-The plugins are described in more detail in chapter :doc:`Plugins reference <../resources/plugin_reference>`.
-There are even more plugins available on the django CMS `extensions page`_.
+The plugins are described in more detail in chapter :doc:`Plugins reference
+<../basic_reference/plugin_reference>`. There are even more plugins available on the django CMS
+`extensions page`_.
 
 .. _snippet_plugin: https://github.com/divio/djangocms-snippet
 .. _extensions page: http://www.django-cms.org/en/extensions/
@@ -642,14 +643,14 @@ the django CMS "Installation Successful" screen.
 
 |it-works-cms|
 
-.. |it-works-cms| image:: ../../images/it-works-cms.png
+.. |it-works-cms| image:: ../images/it-works-cms.png
 
 Use the new side-frame-based administration by appending '?edit' to your URL
 as follows: `http://127.0.0.1:8000/?edit`. This will reveal a login form.
 
 |login-form|
 
-.. |login-form| image:: ../../images/login-form.png
+.. |login-form| image:: ../images/login-form.png
 
 Log in with the user you created during the database setup.
 
@@ -670,7 +671,7 @@ Once in the admin part of your site, you should see something like the following
 
 |logged-in|
 
-.. |logged-in| image:: ../../images/logged-in.png
+.. |logged-in| image:: ../images/logged-in.png
 
 
 Adding a page
@@ -681,19 +682,19 @@ Adding a page is as simple as clicking the "Pages..." menu-item in the
 
 |pages-menu-item|
 
-.. |pages-menu-item| image:: ../../images/pages-menu-item.png
+.. |pages-menu-item| image:: ../images/pages-menu-item.png
 
 This will reveal the new side-frame for administration.
 
 |no-pages|
 
-.. |no-pages| image:: ../../images/no-pages.png
+.. |no-pages| image:: ../images/no-pages.png
 
 Now, click the "add page" button at the top right-hand corner of the side-frame.
 
 |basic-page-form|
 
-.. |basic-page-form| image:: ../../images/basic-page-form.png
+.. |basic-page-form| image:: ../images/basic-page-form.png
 
 This is a basic form where you complete the title of the new page. The slug
 field is also required but a sensible value will be completed as you type the
@@ -704,14 +705,14 @@ pages.
 
 |my-first-page|
 
-.. |my-first-page| image:: ../../images/my-first-page.png
+.. |my-first-page| image:: ../images/my-first-page.png
 
 
 You can click the page title in the "page tree" to navigate to the page in the main window.
 
 |empty-page|
 
-.. |empty-page| image:: ../../images/empty-page.png
+.. |empty-page| image:: ../images/empty-page.png
 
 
 Congratulations! You now have a fully functional django CMS installation!
@@ -732,7 +733,7 @@ page menu invoked.
 
 |page-options|
 
-.. |page-options| image:: ../../images/page-options.png
+.. |page-options| image:: ../images/page-options.png
 
 
 Menus
@@ -779,7 +780,7 @@ displayed "inside" the placeholder as shown in this progession of images.
 
 |add-text-plugin|
 
-.. |add-text-plugin| image:: ../../images/add-text-plugin.png
+.. |add-text-plugin| image:: ../images/add-text-plugin.png
 
 To preview the page, click the "Content" mode button in the toolbar. You can
 continue editing existing plugins in Content mode simply by double-clicking