Issue 5521 - Restructure CMS documentation to make it easier to use and extend

README.md

 # CMS #
 
 We use this CMS for [adblockplus.org](https://github.com/adblockplus/web.adblockplus.org/)
 and related websites. It converts a directory with content data into static
 files. You are free to use it for other projects but please keep in mind that we
 make no stability guarantees whatsoever and might change functionality any time.
 
 ## Getting started ##

[ire, 2017/12/04 10:17:13]

This change is opinionated. I moved everything to the docs/ directory, but
thought there should be some "getting started" info on the main readme page, so
I added the "running the test server" bit here as well.

 
 The easiest way to get started is to run a test server. The test server will 
 convert your content directory on the fly, your changes will become visible 
 immediately. To run it you need:
 
 * Python 2.7
 * [Jinja2](http://jinja.pocoo.org/) and
   [Markdown](https://pypi.python.org/pypi/Markdown) modules (can be installed by
   running `easy_install Jinja2 Markdown` from the command line)
 * A current copy of the
@@ skipping 17 matching lines @@
 There you should generate static files as explained below.
 
 ## Documentation ##
 
 - How to use
     - [Running the test server](docs/usage/test-server.md)
     - [Generating the standalone test server](docs/usage/standalone-test-server.md)
     - [Generating static files](docs/usage/generate-static-files.md)
     - [Syncing translations](docs/usage/syncing-translations.md)
 - Content structure
-    - [Configuration (`settings.ini`)](docs/structure/settings.md)

[Vasily Kuznetsov, 2017/12/12 15:35:24]

I think I prefer to call the folder `docs/content` instead of `docs/structure`
-- seems more intuitively clear what's in it.

[ire, 2017/12/13 11:10:24]

I agree. Done.

-    - [Custom Jinja2 global functions and variables (`globals`)](docs/structure/globals.md)
-    - [Custom Jinja2 filters (`filters`)](docs/structure/filters.md)

[Vasily Kuznetsov, 2017/12/12 15:35:25]

This link is broken, the file is called `filter.md`.

[ire, 2017/12/13 11:10:23]

Done.

-    - [Localization files (`locales`)](docs/structure/locales.md)
-    - [Page layout templates (`templates`)](docs/structure/templates.md)
-    - [Various include files (`includes`)](docs/structure/includes.md)
-    - [User-visible pages (`pages`)](docs/structure/pages.md)
-    - [Static content (`static`)](docs/structure/static.md)
+    - [Configuration (`settings.ini`)](docs/content/settings.md)
+    - [Custom Jinja2 global functions and variables (`globals`)](docs/content/globals.md)
+    - [Custom Jinja2 filters (`filters`)](docs/content/filters.md)
+    - [Localization files (`locales`)](docs/content/locales.md)
+    - [Page layout templates (`templates`)](docs/content/templates.md)
+    - [Various include files (`includes`)](docs/content/includes.md)
+    - [User-visible pages (`pages`)](docs/content/pages.md)
+    - [Static content (`static`)](docs/content/static.md)
 - API

[ire, 2017/12/04 10:17:13]

In the future I hope for the API documentation to be here (which will list all
the CMS methods we can use). This bullet point can be removed until that
documentation is added.

[Vasily Kuznetsov, 2017/12/12 15:35:24]

Yeah, we need API documentation. Perhaps the part of `pages.md` that talks about
variables, functions and filters available to templates could for the initial
version of this section. And then it could be linked from `pages.md`.

[ire, 2017/12/13 11:10:23]

I like this idea. 

I arranged this into 3 files - variables, filters, and functions. I don't know
if this is the ideal way to categorise them, I think organising them by topic
may be better, e.g. "translation", etc. But until we have a fuller
documentation, I think this could work. Let me know what you think.

+    - [Variables](docs/api/variables.md)
+    - [Custom filters](docs/api/filters.md)
+    - [Global functions](docs/api/functions.md)