Permalink
Browse files

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.
  • Loading branch information...
1 parent a8c3806 commit 52a480beec529955cf2ebbd618666520c238ad39 @evildmp evildmp committed Jul 14, 2014
View
16 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
View
0 ...tting_started/resources/configuration.rst → docs/basic_reference/configuration.rst
File renamed without changes.
View
15 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
View
0 .../getting_started/resources/navigation.rst → docs/basic_reference/navigation.rst
File renamed without changes.
View
0 ...ng_started/resources/plugin_reference.rst → docs/basic_reference/plugin_reference.rst
File renamed without changes.
View
0 ...getting_started/resources/using_south.rst → docs/basic_reference/using_south.rst
File renamed without changes.
View
12 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
View
5 docs/concepts/introduction.rst
@@ -1,5 +0,0 @@
-############
-Introduction
-############
-
-This section doesn't explain how to do anything, but explains and analyses some key concepts in django CMS.
View
8 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.
-
-
-
-
View
10 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
View
17 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
View
22 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
View
35 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
+
View
29 ...etting_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
View
109 docs/index.rst
@@ -19,113 +19,20 @@ Release Notes
:ref:`Upgrading from previous versions <upgrade-to-3.0>`
-.. toctree::
- :maxdepth: 1
-
-
- upgrade/3.0.3
- upgrade/3.0
- upgrade/2.4
- upgrade/2.3.4
- upgrade/2.3.3
- upgrade/2.3.2
- upgrade/2.3
- upgrade/2.2
- upgrade/2.1
-
-
-***************
-Getting Started
-***************
-
-Installation
-============
-
-.. toctree::
- :maxdepth: 2
- :numbered:
-
- getting_started/installation/index
- getting_started/installation/integrate
- getting_started/tutorial
-
-
-Resources
-=========
-
-.. toctree::
- :maxdepth: 2
- :numbered:
-
- getting_started/resources/configuration
- getting_started/resources/navigation
- getting_started/resources/plugin_reference
- getting_started/resources/using_south
- faq/common_issues
-
-
*****************
-Extending the CMS
+Table of contents
*****************
.. toctree::
:maxdepth: 2
- :numbered:
-
- extending_cms/extending_examples
- extending_cms/extending_page_title
- extending_cms/custom_plugins
- extending_cms/app_integration
- extending_cms/api_references
- extending_cms/placeholders
- extending_cms/toolbar
- extending_cms/frontend_models
- extending_cms/searchdocs
- extending_cms/fields
- extending_cms/testing
-
-
-********
-Advanced
-********
-
-.. toctree::
- :maxdepth: 2
- :numbered:
-
- advanced/i18n
- advanced/caching
- advanced/sitemap
- advanced/templatetags
- advanced/cli
- advanced/permissions_reference
-
-
-********
-Concepts
-********
-
-.. toctree::
- :maxdepth: 2
- :numbered:
-
- concepts/introduction
- concepts/menu_system
- concepts/publishing
- concepts/multiple_languages
-
-
-**************************
-Contributing to django CMS
-**************************
-
-.. toctree::
- :maxdepth: 2
- :numbered:
-
- contributing/contributing
- contributing/testing
+ getting_started/index
+ basic_reference/index
+ extending_cms/index
+ advanced/index
+ concepts/index
+ contributing/index
+ upgrade/index
Indices and tables
View
19 docs/upgrade/2.1.rst
@@ -1,9 +1,10 @@
-*************************************
+#####################################
Upgrading from 2.1.x and Django 1.2.x
-*************************************
+#####################################
+**********************
Upgrading dependencies
-======================
+**********************
Upgrade both your version of django CMS and Django by running
the following commands.
@@ -26,8 +27,9 @@ with django CMS
pip install --upgrade django-mptt==0.5.1
+**************************
Updates to ``settings.py``
-==========================
+**************************
The following changes will need to be made in your settings.py file::
@@ -73,8 +75,9 @@ The following changes will need to be made in your settings.py file::
sekizai
django.contrib.staticfiles
+****************
Template Updates
-================
+****************
Make sure to add sekizai tags and ``cms_toolbar`` to your CMS templates.
@@ -99,8 +102,9 @@ Here is a simple example for a base template called ``base.html``:
</body>
</html>
+****************
Database Updates
-================
+****************
Run the following commands to upgrade your database
@@ -109,8 +113,9 @@ Run the following commands to upgrade your database
python manage.py syncdb
python manage.py migrate
+************
Static Media
-============
+************
Add the following to ``urls.py`` to serve static media when developing::
View
22 docs/upgrade/index.rst
@@ -0,0 +1,22 @@
+##########################################
+Release notes and information on upgrading
+##########################################
+
+Some versions of django CMS present more complex upgrade paths than others, and some **require** you
+to take action. It is strongly recommended to read the release notes carefully when upgrading.
+
+It goes without saying that you should **backup your database** before embarking on any process that
+makes changes to your database.
+
+.. toctree::
+ :maxdepth: 1
+
+ 3.0.3
+ 3.0
+ 2.4
+ 2.3.4
+ 2.3.3
+ 2.3.2
+ 2.3
+ 2.2
+ 2.1

0 comments on commit 52a480b

Please sign in to comment.