[#943] Rearrange the writing extensions docs

But the different parts into different pages

ckan/logic/__init__.py

@@ -488,7 +488,7 @@ def side_effect_free(action):
     '''A decorator that marks the given action function as side-effect-free.
 
     Action functions decorated with this decorator can be called with an HTTP
-    GET request to the :doc:`Action API <api>`. Action functions that don't
+    GET request to the :doc:`Action API </api>`. Action functions that don't
     have this decorator must be called with a POST request.
 
     If your CKAN extension defines its own action functions using the
@@ -521,7 +521,7 @@ def auth_sysadmins_check(action):
     to call an action function.
 
     Normally sysadmins are allowed to call any action function (for example
-    when they're using the :doc:`Action API <api>` or the web interface),
+    when they're using the :doc:`Action API </api>` or the web interface),
     if the user is a sysadmin the action function's authorization function
     will not even be called.
 

ckan/plugins/toolkit.py

@@ -212,7 +212,7 @@ def _initialize(self):
     def _render_snippet(cls, template, data=None):
         '''Render a template snippet and return the output.
 
-        See :doc:`theming`.
+        See :doc:`/theming`.
 
         '''
         data = data or {}
@@ -262,7 +262,7 @@ def _add_resource(cls, path, name):
         Fanstatic libraries are directories containing static resource files
         (e.g. CSS, JavaScript or image files) that can be accessed from CKAN.
 
-        See :doc:`theming` for more details.
+        See :doc:`/theming` for more details.
 
         '''
         # we want the filename that of the function caller but they will

ckan/plugins/toolkit_sphinx_extension.py

@@ -8,11 +8,11 @@
 Sphinx extension to automate documenting it instead.
 
 This extension plugs into the reading phase of the Sphinx build. It intercepts
-the 'toolkit' document (toolkit.rst) after Sphinx has read the reStructuredText
-source from file. It modifies the source, adding in Sphinx directives for
-everything in the plugins toolkit, and then the Sphinx build continues as
-normal (just as if the generated reStructuredText had been entered into
-toolkit.rst manually before running Sphinx).
+the 'toolkit' document (extensions/plugins-toolkit.rst) after Sphinx has read
+the reStructuredText source from file. It modifies the source, adding in Sphinx
+directives for everything in the plugins toolkit, and then the Sphinx build
+continues as normal (just as if the generated reStructuredText had been entered
+into plugins-toolkit.rst manually before running Sphinx).
 
 '''
 import types
@@ -142,11 +142,11 @@ def format_object(name, object_, docstring=None):
 
 
 def source_read(app, docname, source):
-    '''Transform the contents of toolkit.rst to contain reference docs.
+    '''Transform the contents of plugins-toolkit.rst to contain reference docs.
 
     '''
-    # We're only interested in the 'toolkit' doc (toolkit.rst).
-    if docname != 'toolkit':
+    # We're only interested in the 'plugins-toolkit' doc (plugins-toolkit.rst).
+    if docname != 'extensions/plugins-toolkit':
         return
 
     source_ = ''

doc/background-tasks.rst

@@ -7,7 +7,7 @@ Background Tasks
 CKAN allows you to create tasks that run in the 'background', that is
 asynchronously and without blocking the main application (these tasks can also
 be automatically retried in the case of transient failures). Such tasks can be
-created in :doc:`Extensions <writing-extensions>` or in core CKAN.
+created in :doc:`Extensions <extensions/index>` or in core CKAN.
 
 Background tasks can be essential to providing certain kinds of functionality,
 for example:

doc/ckan-coding-standards.rst

@@ -195,13 +195,13 @@ See :doc:`test` for further information on testing in CKAN.
 Writing Extensions
 ------------------
 
-Please see :doc:`writing-extensions` for information about writing ckan
+Please see :doc:`extensions/index` for information about writing ckan
 extensions, including details on the API available to extensions.
 
 Deprecation
 -----------
 
-- Anything that may be used by extensions (see :doc:`writing-extensions`) needs
+- Anything that may be used by extensions (see :doc:`extensions/index`) needs
   to maintain backward compatibility at call-site.  ie - template helper
   functions and functions defined in the plugins toolkit.
 

doc/configuration.rst

@@ -506,7 +506,7 @@ Specify which CKAN plugins are to be enabled.
 
 .. warning::  If you specify a plugin but have not installed the code,  CKAN will not start.
 
-Format as a space-separated list of the plugin names. The plugin name is the key in the ``[ckan.plugins]`` section of the extension's ``setup.py``. For more information on plugins and extensions, see :doc:`writing-extensions`.
+Format as a space-separated list of the plugin names. The plugin name is the key in the ``[ckan.plugins]`` section of the extension's ``setup.py``. For more information on plugins and extensions, see :doc:`extensions/index`.
 
 .. _ckan.datastore.enabled:
 

doc/data-viewer.rst

@@ -31,7 +31,7 @@ provide instructions for how to enable each extension.
 It is also possible for developers to create new extensions that can preview
 different types of resources.
 For more information on this topic see
-`Writing Extensions <writing-extensions.html>`_.
+`Writing Extensions <extensions/index>`_.
 
 
 .. _image-preview:

doc/documentation-guidelines.rst

@@ -462,7 +462,7 @@ therefore more likely to be kept up to date.
 Whenever you're writing reference documentation for modules, classes, functions
 or methods, exceptions, attributes, etc. you should probably be using autodoc.
 For example, we use autodoc for the :ref:`api-reference`, the
-:ref:`plugin interfaces reference`, etc.
+:doc:`extensions/plugin-interfaces`, etc.
 
 For how to write docstrings, see :ref:`docstrings`.
 

doc/extensions/best-practices.rst

@@ -0,0 +1,26 @@
+-------------------------------------
+Best practices for writing extensions
+-------------------------------------
+
+Follow CKAN's coding standards
+==============================
+
+See :ref:`coding standards`.
+
+Use the plugins toolkit instead of importing CKAN
+=================================================
+
+Try to limit your extension to interacting with CKAN only through CKAN's
+:doc:`plugin interfaces <plugin-interfaces>` and
+:doc:`plugins toolkit <plugins-toolkit>`. It's a good idea to keep your
+extension code separate from CKAN as much as possible, so that internal changes
+in CKAN from one release to the next don't break your extension.
+
+
+Don't edit CKAN's database tables
+=================================
+
+An extension can create its own tables in the CKAN database, but it should
+write to core CKAN tables directly, add columns to core tables, or use foreign
+keys against core tables.
+

doc/extensions/converters.rst

@@ -0,0 +1,7 @@
+Converter functions reference
+=============================
+
+.. automodule:: ckan.logic.converters
+   :members:
+   :undoc-members:
+

doc/extensions/index.rst

@@ -0,0 +1,32 @@
+=======================
+Writing CKAN extensions
+=======================
+
+CKAN can be modified and extended using extensions. Some **core extensions**
+come packaged with CKAN. Core extensions don't need to be installed before you
+can use them as they're installed when you install CKAN, they can simply be
+enabled by following the setup instructions in each extension's documentation
+(some core extensions are already enabled by default). For example, the
+:doc:`datastore extension </datastore>`, :doc:`multilingual extension
+</multilingual>`, and :doc:`stats extension </stats>` are all core extensions,
+and the :doc:`data viewer </data-viewer>` also uses core extensions to enable
+data previews for different file formats.
+
+**External extensions** are CKAN extensions that don't come packaged with
+CKAN, but must be downloaded and installed separately. A good place to find
+external extensions is the
+`list of extensions on the CKAN wiki <https://github.com/okfn/ckan/wiki/List-of-extensions>`_.
+Again, follow each extension's own documentation to install, setup and use the
+extension.
+
+This document covers everything you need to know to write your own CKAN
+extensions.
+
+.. toctree::
+   :maxdepth: 2
+
+   tutorial
+   best-practices
+   plugin-interfaces
+   plugins-toolkit
+   converters

doc/extensions/plugin-interfaces.rst

@@ -0,0 +1,9 @@
+Plugin interfaces reference
+===========================
+
+.. automodule:: ckan.plugins.core
+        :members:  SingletonPlugin, Plugin, implements
+
+.. automodule:: ckan.plugins.interfaces
+        :members:
+

doc/toolkit.rst → doc/extensions/plugins-toolkit.rst

@@ -1,6 +1,6 @@
----------------
-Plugins toolkit
----------------
+-------------------------
+Plugins toolkit reference
+-------------------------
 
 As well as using the variables made available to them by implementing plugin
 interfaces, plugins will likely want to be able to use parts of the CKAN core