diff --git a/doc/conf.py b/doc/conf.py
index e5c33312cfc..bff9026ef94 100644
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -62,6 +62,8 @@
.. |nginx_config_file| replace:: /etc/nginx/sites-available/ckan_default
.. |reload_nginx| replace:: sudo service nginx reload
+.. _CKAN issue tracker: https://github.com/okfn/ckan/issues
+
'''
# Add any Sphinx extension module names here, as strings. They can be extensions
diff --git a/doc/contributing/coding-standards/ckan-code-architecture.rst b/doc/contributing/architecture.rst
similarity index 100%
rename from doc/contributing/coding-standards/ckan-code-architecture.rst
rename to doc/contributing/architecture.rst
diff --git a/doc/contributing/coding-standards/index.rst b/doc/contributing/coding-standards/index.rst
deleted file mode 100644
index 95c343e50c0..00000000000
--- a/doc/contributing/coding-standards/index.rst
+++ /dev/null
@@ -1,17 +0,0 @@
-=====================
-CKAN Coding Standards
-=====================
-
-When writing code for CKAN, please follow our coding standards:
-
-.. toctree::
- :maxdepth: 1
-
- ckan-code-architecture
- python-coding-standards
- html-coding-standards
- css-coding-standards
- javascript-coding-standards
- testing-coding-standards
- database-migrations
- upgrading-dependencies
diff --git a/doc/contributing/commit-messages.rst b/doc/contributing/commit-messages.rst
new file mode 100644
index 00000000000..ff2de239c33
--- /dev/null
+++ b/doc/contributing/commit-messages.rst
@@ -0,0 +1,37 @@
+=======================
+Writing commit messages
+=======================
+
+We use the version control system `git `_ for our code
+and documentation, so when contributing code or docs you'll have to commit
+your changes to git and write a git commit message.
+Generally, follow the `commit guidelines from the Pro Git book`_:
+
+- Try to make each commit a logically separate, digestible changeset.
+
+- The first line of the commit message should concisely summarise the
+ changeset.
+
+- Optionally, follow with a blank line and then a more detailed explanation of
+ the changeset.
+
+- Use the imperative present tense as if you were giving commands to the
+ codebase to change its behaviour, e.g. *Add tests for...*, *make xyzzy do
+ frotz...*, this helps to make the commit message easy to read.
+
+.. _commit guidelines from the Pro Git book: http://git-scm.com/book/en/Distributed-Git-Contributing-to-a-Project#Commit-Guidelines
+
+If your commit has an issue in the `CKAN issue tracker`_ put the issue number
+at the start of the first line of the commit message like this: ``[#123]``.
+This makes the CKAN release manager's job much easier!
+
+Here's an example of a good CKAN commit message::
+
+ [#607] Allow reactivating deleted datasets
+
+ Currently if a dataset is deleted and users navigate to the edit form,
+ there is no state field and the delete button is still shown.
+
+ After this change, the state dropdown is shown if the dataset state is
+ not active, and the delete button is not shown.
+
diff --git a/doc/contributing/coding-standards/css-coding-standards.rst b/doc/contributing/css.rst
similarity index 100%
rename from doc/contributing/coding-standards/css-coding-standards.rst
rename to doc/contributing/css.rst
diff --git a/doc/contributing/coding-standards/database-migrations.rst b/doc/contributing/database-migrations.rst
similarity index 100%
rename from doc/contributing/coding-standards/database-migrations.rst
rename to doc/contributing/database-migrations.rst
diff --git a/doc/contributing/documentation-guidelines.rst b/doc/contributing/documentation.rst
similarity index 96%
rename from doc/contributing/documentation-guidelines.rst
rename to doc/contributing/documentation.rst
index 512c702db64..0b4989cba26 100644
--- a/doc/contributing/documentation-guidelines.rst
+++ b/doc/contributing/documentation.rst
@@ -1,16 +1,20 @@
-========================
-Documentation guidelines
-========================
+=====================
+Writing documentation
+=====================
.. _docs.ckan.org: http://docs.ckan.org
-The quickest and easiest way to contribute documentation to CKAN is to sign up
-for a free GitHub account and simply edit the `CKAN Wiki `_.
-Docs started on the wiki can make it onto `docs.ckan.org`_ later.
+.. seealso::
+
+ The quickest and easiest way to contribute documentation to CKAN is to sign up
+ for a free GitHub account and simply edit the `CKAN Wiki `_.
+ Docs started on the wiki can make it onto `docs.ckan.org`_ later.
+ If you do want to contribute to `docs.ckan.org`_ directly, follow the
+ instructions on this page.
-**Tip**: Use the reStructuredText markup format when creating a wiki page,
-since reStructuredText is the format that docs.ckan.org uses, this will make
-moving the documentation from the wiki into docs.ckan.org later easier.
+ **Tip**: Use the reStructuredText markup format when creating a wiki page,
+ since reStructuredText is the format that docs.ckan.org uses, this will make
+ moving the documentation from the wiki into docs.ckan.org later easier.
This section gives some guidelines to help us to write consistent and good
quality documentation for CKAN.
diff --git a/doc/contributing/frontend/index.rst b/doc/contributing/frontend/index.rst
index 0160653ef27..7232c736d46 100644
--- a/doc/contributing/frontend/index.rst
+++ b/doc/contributing/frontend/index.rst
@@ -1,5 +1,5 @@
===============================
-Frontend Development Guidelines
+Frontend development guidelines
===============================
.. toctree::
@@ -11,9 +11,9 @@ Frontend Development Guidelines
template-blocks
javascript-module-tutorial
-------------------------------
-Install front end dependencies
-------------------------------
+-----------------------------
+Install frontend dependencies
+-----------------------------
The front end stylesheets are written using
`LESS `_ (this depends on
@@ -39,7 +39,7 @@ style script.
$ npm install less nodewatch
--------------
-File Structure
+File structure
--------------
All front-end files to be served via a web server are located in the
@@ -202,7 +202,7 @@ factory function.
A guide on creating your own modules is located in the
:doc:`javascript-module-tutorial` guide.
-Publisher/Subscriber
+Publisher/subscriber
====================
There is a simple pub/sub module included under ``ckan.pubsub`` it's
@@ -289,7 +289,7 @@ And we name the translate function passed into ``ckan.module()`` ``_``.
};
});
-Life Cycle
+Life cycle
==========
CKAN modules are intialised on dom ready. The ``ckan.module.initialize()``
@@ -348,8 +348,8 @@ retrieving them.
});
-jQuery Plug-ins
-===============
+jQuery plugins
+==============
Any functionality that is not directly related to ckan should be
packaged up in a jQuery plug-in if possible. This keeps the modules
@@ -359,7 +359,7 @@ other sites.
Examples of these are ``jQuery.fn.slug()``, ``jQuery.fn.slugPreview()``
and ``jQuery.proxyAll()``.
-Unit Tests
+Unit tests
==========
There is currently a test suite available at:
diff --git a/doc/contributing/coding-standards/html-coding-standards.rst b/doc/contributing/html.rst
similarity index 100%
rename from doc/contributing/coding-standards/html-coding-standards.rst
rename to doc/contributing/html.rst
diff --git a/doc/contributing/i18n.rst b/doc/contributing/i18n.rst
index 6763de6e7e5..ffd72f88144 100644
--- a/doc/contributing/i18n.rst
+++ b/doc/contributing/i18n.rst
@@ -1,6 +1,6 @@
-======================================
-Internationalizing and localizing CKAN
-======================================
+================
+Translating CKAN
+================
CKAN is used in many countries, and adding a new language to the web interface is a simple process.
diff --git a/doc/contributing/index.rst b/doc/contributing/index.rst
index 0ef49dece81..f2e62229d36 100644
--- a/doc/contributing/index.rst
+++ b/doc/contributing/index.rst
@@ -10,12 +10,28 @@ they're bug reports, source code, documentation or translations. The following
documents will walk you through our processes for making different kinds
of contributions to CKAN:
+.. If editing this, note that these are roughly ordered with the most simple
+ forms of contribution (for non-developers) first, and then the more advanced
+ technical topics after.
+
.. toctree::
:maxdepth: 1
issues
i18n
- documentation-guidelines
- coding-standards/index
- frontend/index
+
+ commit-messages
pull-requests
+ reviewing
+
+ documentation
+ architecture
+ css
+ html
+ javascript
+ python
+ testing
+ frontend/index
+
+ database-migrations
+ upgrading-dependencies
diff --git a/doc/contributing/issues.rst b/doc/contributing/issues.rst
index c5e440d2b3e..43517f8336e 100644
--- a/doc/contributing/issues.rst
+++ b/doc/contributing/issues.rst
@@ -1,5 +1,5 @@
================
-Reporting Issues
+Reporting issues
================
If you've found a bug in CKAN, open a new issue on CKAN's `GitHub Issues`_ (try
diff --git a/doc/contributing/coding-standards/javascript-coding-standards.rst b/doc/contributing/javascript.rst
similarity index 99%
rename from doc/contributing/coding-standards/javascript-coding-standards.rst
rename to doc/contributing/javascript.rst
index 527bcde24a1..cb4a3a8798f 100644
--- a/doc/contributing/coding-standards/javascript-coding-standards.rst
+++ b/doc/contributing/javascript.rst
@@ -1,5 +1,5 @@
===========================
-Javascript coding standards
+JavaScript coding standards
===========================
----------
diff --git a/doc/contributing/pull-requests.rst b/doc/contributing/pull-requests.rst
index 503bbff823d..98b05c9f4dd 100644
--- a/doc/contributing/pull-requests.rst
+++ b/doc/contributing/pull-requests.rst
@@ -1,8 +1,6 @@
----------------------
-Making a Pull Request
----------------------
-
-.. _CKAN issue tracker: https://github.com/okfn/ckan/issues
+=====================
+Making a pull request
+=====================
Once you've written some CKAN code or documentation, you can submit it for
review and merge into the central CKAN git repository by making a pull request.
@@ -44,8 +42,8 @@ This section will walk you through the steps for making a pull request.
git commit -m "Add docs for my new feature"
git push my_fork my_branch
- When writing your git commit messages, try to follow the `Commit Messages`_
- guidelines.
+ When writing your git commit messages, try to follow the
+ :doc:`commit-messages` guidelines.
#. Send a pull request
@@ -62,14 +60,14 @@ This section will walk you through the steps for making a pull request.
- Your branch should contain one logically separate piece of work, and not
any unrelated changes.
- - You should have good commit messages, see `Commit Messages`_.
+ - You should have good commit messages, see :doc:`commit-messages`.
- Your branch should contain new or changed tests for any new or changed
code, and all the CKAN tests should pass on your branch, see
`Testing CKAN `_.
- Your branch should contain new or updated documentation for any new or
- updated code, see :doc:`documentation-guidelines`.
+ updated code, see :doc:`documentation`.
- Your branch should be up to date with the master branch of the central
CKAN repo, so pull the central master branch into your feature branch
@@ -80,45 +78,3 @@ This section will walk you through the steps for making a pull request.
much.
.. _create a pull request on GitHub: https://help.github.com/articles/creating-a-pull-request
-
-
-Merging a Pull Request
-======================
-
-If you're reviewing a pull request for CKAN, when merging a branch into master:
-
-- Use the ``--no-ff`` option in the ``git merge`` command,
-
----------------
-Commit Messages
----------------
-
-Generally, follow the `commit guidelines from the Pro Git book`_:
-
-- Try to make each commit a logically separate, digestible changeset.
-
-- The first line of the commit message should concisely summarise the
- changeset.
-
-- Optionally, follow with a blank line and then a more detailed explanation of
- the changeset.
-
-- Use the imperative present tense as if you were giving commands to the
- codebase to change its behaviour, e.g. *Add tests for...*, *make xyzzy do
- frotz...*, this helps to make the commit message easy to read.
-
-.. _commit guidelines from the Pro Git book: http://git-scm.com/book/en/Distributed-Git-Contributing-to-a-Project#Commit-Guidelines
-
-If your commit has an issue in the `CKAN issue tracker`_ put the issue number
-at the start of the first line of the commit message like this: ``[#123]``.
-This makes the CKAN release manager's job much easier!
-
-Here's an example of a good CKAN commit message::
-
- [#607] Allow reactivating deleted datasets
-
- Currently if a dataset is deleted and users navigate to the edit form,
- there is no state field and the delete button is still shown.
-
- After this change, the state dropdown is shown if the dataset state is
- not active, and the delete button is not shown.
diff --git a/doc/contributing/coding-standards/python-coding-standards.rst b/doc/contributing/python.rst
similarity index 100%
rename from doc/contributing/coding-standards/python-coding-standards.rst
rename to doc/contributing/python.rst
diff --git a/doc/contributing/reviewing.rst b/doc/contributing/reviewing.rst
new file mode 100644
index 00000000000..a26ae504e25
--- /dev/null
+++ b/doc/contributing/reviewing.rst
@@ -0,0 +1,15 @@
+====================================
+Reviewing and merging a pull request
+====================================
+
+.. todo::
+
+ Put some more detailed docs here about how to review a CKAN pull request.
+
+----------------------
+Merging a pull request
+----------------------
+
+If you're reviewing a pull request for CKAN, when merging a branch into master:
+
+- Use the ``--no-ff`` option in the ``git merge`` command
diff --git a/doc/contributing/coding-standards/testing-coding-standards.rst b/doc/contributing/testing.rst
similarity index 100%
rename from doc/contributing/coding-standards/testing-coding-standards.rst
rename to doc/contributing/testing.rst
diff --git a/doc/contributing/coding-standards/upgrading-dependencies.rst b/doc/contributing/upgrading-dependencies.rst
similarity index 100%
rename from doc/contributing/coding-standards/upgrading-dependencies.rst
rename to doc/contributing/upgrading-dependencies.rst
diff --git a/doc/extensions/best-practices.rst b/doc/extensions/best-practices.rst
index b251509f4bb..eeee5118887 100644
--- a/doc/extensions/best-practices.rst
+++ b/doc/extensions/best-practices.rst
@@ -7,7 +7,7 @@ Best practices for writing extensions
Follow CKAN's coding standards
------------------------------
-See :doc:`/contributing/coding-standards/index`.
+See :doc:`/contributing/index`.
-------------------------------------------------