doc: Improve docs for 1.0 (#1458)

* doc: Move template icons to cookbook chapter

* doc: Improve docs for 1.0

* Add introduction to docs organization.
* Make font for code samples a little larger.
* Add introductions to reference guides.
* Replace 'Installation' With 'Getting Started'.
* Clean up developer guide chapters: Templates.
* Clean up reference: config and other sections.

doc/_static/overrules.css

@@ -12,4 +12,13 @@ div.version:before {
 .wy-menu-vertical a:hover {
   color: #ffffff;
   background-color: #195c88;
-}
+}
+
+div.highlight pre {
+    font-size: .8em;
+}
+
+span.pre {
+    border: none;
+    color: #404040;
+}

doc/best-practices/media.rst

@@ -0,0 +1,4 @@
+Media Best Practices
+====================
+
+* Use :ref:`guide-media-classes` to define image properties.

doc/cookbook/custom-filter.rst

@@ -0,0 +1,6 @@
+.. _cookbook-custom-filter:
+
+Create a custom filter
+======================
+
+.. todo:: this chapter

doc/cookbook/index.rst

@@ -7,12 +7,15 @@ Cookbooks
    :maxdepth: 1
 
    custom-action
+   custom-filter
    custom-model
    custom-pivot
    pivot-templates
    custom-tag
    writing-module
+   overriding
    task-queue
+   template-icons
 
 Frontend cookbook
 -----------------

doc/cookbook/overriding.rst

@@ -0,0 +1,32 @@
+.. _cookbook-overriding:
+
+Overriding Zotonic
+==================
+
+This chapter describes how to override the templates, styling and logic
+provided by Zotonic.
+
+Overriding works by adding a site or module that has a higher
+:ref:`priority <module-priority>` than Zotonic’s built-in modules. In your
+module/site, you add templates, assets and create notification observers.
+
+Overriding templates
+--------------------
+
+:ref:`Override templates <overriding-templates>` by adding a template with
+the same name to your module/site.
+
+Overriding assets
+-----------------
+
+If you wish to fully override a CSS or JavaScript file, do so in the same way
+as you do templates: create a file with the same name in your module/site.
+Alternatively, *add* your own CSS file and selectively override CSS styles.
+
+Overriding logic
+----------------
+
+:ref:`Observe notifications <guide-notifications-observe>` to influence the
+decisions that Zotonic makes. You can change or add properties before a resource
+is persisted,
+

doc/cookbook/template-icons.rst

@@ -0,0 +1,40 @@
+Icons in templates
+==================
+
+Zotonic provides a couple of ways to show icons in templates:
+
+* :ref:`mod_artwork` gives access to FontAwesome and Material Design icons.
+  It also has a number of other icon collections, mostly PNG images. Activate
+  the module and follow the instructions on the doc page.
+* Zotonic icons provided by `mod_base`. This is explained on the current page.
+
+To create a certain amount of consistency across modules, Zotonic comes with a
+small set of commonly used icons and CSS classes (edit, help, close, etcetera)
+plus the Zotonic logo.
+
+Use cases:
+
+* You create your frontend from scratch, but you also have pages in your site
+  that are provided by other modules, for instance the login screens. It would
+  be good if the social login icons show up.
+* You are writing a template or module and like to take advantage of ready
+  available icons.
+* You are writing frontend styles in LESS and you would like to extend Zotonic
+  / FontAwesome / Material Design icons.
+
+Include the Zotonic icons CSS file in your template::
+
+    {% lib
+        "css/z.icons.css"
+    %}
+
+Then use this syntax in your template HTML::
+
+    z-icon z-icon-<name>
+
+For instance::
+
+    <span class="z-icon z-icon-off"></span>
+
+.. seealso:: :ref:`ref-icons` reference
+

doc/cookbook/writing-module.rst

@@ -1,3 +1,5 @@
+.. _cookbook-custom-module:
+
 Writing your own module
 =======================
 

doc/developer-guide/controllers.rst

@@ -34,6 +34,11 @@ The simplest controller uses Zotonic’s ``controller_html_helper.hrl`` include
    html(Context) ->
        {<<"<h1>Hello</h1>">>, Context}.
 
+.. _guide-render:
+
+Rendering templates
+-------------------
+
 To return the rendered output of a template file in the module's
 ``templates`` directory, use ``z_template:render/3``::
 

doc/developer-guide/installation.rst → doc/developer-guide/getting-started.rst

@@ -1,16 +1,38 @@
 .. highlight:: bash
 
+Getting Started
+===============
+
+You have two options for running Zotonic: to get started quickly, start our
+Zotonic container. Or you can install Zotonic on your computer.
+
+Docker
+------
+
+First `download and install Docker`_ . Then start Zotonic with a single
+command::
+
+    $ docker run -v `pwd`:/opt/zotonic/user/sites -p 8000:8000 zotonic/zotonic-heavy
+
+Docker will download and boot the container. Zotonic will be available on port
+8000 on your machine. So, after Docker has booted, open your browser and go to
+http://localhost:8080 to view the Zotonic Status page. If you wish to quit
+the container, press Ctrl+C.
+
+You can now move on to :ref:`creating your first site <guide-create-site>`.
+
+.. seealso:: :ref:`guide-docker` for more information on our images.
+
 .. _guide-installation:
 
 Installation
-============
+------------
 
-To get Zotonic running, you first need to install it. This chapter describes how
-to install Zotonic manually. Alternatively, you can run Zotonic from one of
-the :ref:`Docker images <guide-docker>`.
+If you don’t like Docker, or you like to do things yourself, you can always
+install Zotonic on your computer yourself.
 
 Preparation
------------
+^^^^^^^^^^^
 
 First prepare your system for running Zotonic. Zotonic needs:
 
@@ -23,15 +45,15 @@ First prepare your system for running Zotonic. Zotonic needs:
     a more extensive discussion of
     :ref:`all requirements <installation-preinstall>`
 
-On Linux
-^^^^^^^^
+Linux
+"""""
 
 For instance on Debian you can install the dependencies by running::
 
     $ sudo apt-get install build-essential git erlang imagemagick postgresql
 
-On OS X
-^^^^^^^
+macOS X
+"""""""
 
 Install Homebrew_, then run::
 
@@ -40,7 +62,7 @@ Install Homebrew_, then run::
 .. _Homebrew: http://brew.sh
 
 On Windows
-^^^^^^^^^^
+""""""""""
 
 Currently, Zotonic is not officially supported on the Windows
 platform. However, the main dependencies Erlang, PostgreSQL and
@@ -53,7 +75,7 @@ up-to-date with recent changes. Expect some major tweaking to get this
 back on track.
 
 Getting Zotonic
----------------
+^^^^^^^^^^^^^^^
 
 1. Download the latest Zotonic release ZIP file from the `GitHub releases page`_. For
    instance:
@@ -94,4 +116,5 @@ Next steps
   :ref:`troubleshooting reference <ref-troubleshooting-installation>`.
 * Read more about Zotonic :ref:`configuration <guide-configuration>`.
 
+.. _download and install Docker: https://www.docker.com/products/docker
 .. _GitHub releases page: https://github.com/zotonic/zotonic/releases

doc/developer-guide/index.rst

@@ -3,21 +3,26 @@
 Developer Guide
 ===============
 
+The technical handbook for developers building websites with Zotonic. It guides
+you through all aspects of the framework.
+
 .. toctree::
    :maxdepth: 1
    :glob:
 
    introduction
-   installation
+   getting-started
    docker
    sites
    controllers
    dispatch-rules
    resources
    templates
+   media
    forms-and-validation
    search
    translation
+   wires
    access-control
    modules
    notifications

doc/developer-guide/media.rst

@@ -0,0 +1,73 @@
+.. highlight:: django
+.. _guide-media:
+
+Media
+=====
+
+Images, video
+
+
+In templates
+------------
+
+.. _guide-media-classes:
+
+Media classes
+-------------
+
+Media classes
+^^^^^^^^^^^^^
+
+Instead of inline image tag parameters, you can use media classes to define
+image transformations. The advantage is that this image definition can then be
+reused amongst templates.
+
+Create a ``templates/mediaclass.config`` file in your site directory:
+
+.. code-block:: erlang
+
+    [
+        {"thumb", [
+            {width, 200},
+            {height, 200},
+            crop
+        ]}
+    ].
+
+This defines a media class called ‘thumb’, which can be used to display a
+120x120 cropped square image. You then only need to refer to this media class in
+your image tag::
+
+    {% image id mediaclass="thumb" %}
+
+The image URL will have a checksum embedded in it so that when the contents of
+the media class is changed, all images which use that media class will be
+regenerated to reflect the new media class.
+
+Raw ImageMagick options
+"""""""""""""""""""""""
+
+Besides the normal image processing options, as described in :ref:`tag-image`,
+it is possible to add literal ImageMagick convert commands to the mediaclass
+definition.
+
+For example::
+
+    {magick, "-level 90%,100% +level-colors \\#FE7D18,\\#331575"}
+
+(Note that you have to double any backslashes that were needed for the
+``convert`` command line.)
+
+This command is given *as-is* to the ImageMagick `convert` command, therefore it
+is best to first try it with the command-line `convert` command to find the
+correct options and command line escapes needed.
+
+There are three variations: ``pre_magick``, ``magick``, and ``post_magick``.
+The only difference is that the ``pre_magick`` is added before any other filter
+argument, ``magick`` somewhere between, and `post_magick` after the last filter.
+
+In this way it is possible to pre- or post-process an image before or after
+resizing.
+
+See http://www.imagemagick.org/Usage/ for examples of using ImageMagick from the
+command line.