start restructuring the Tips & Tricks section, to give eager

contributors of documentation a place to put their good stuff

R1/source/tips/contribdoc/index.rst

+.. _contribdoc:
+
+How to contribute documentation to varnish-cache.org
+====================================================
+
+This is where we walk you through the mechanics of adding content to
+varnish-cache.org (see phk's note :ref:`20160425_website` for an
+insight into the innards of site).
+
+Git Repository
+--------------
+
+The web site contents live in github at:
+
+https://github.com/varnishcache/homepage
+
+To offer your own contribution, fork the project and send us a pull
+request.
+
+Sphinx and RST
+--------------
+
+The web site sources are written in `RST
+<http://docutils.sourceforge.net/rst.html>`_ -- reStructuredText, the
+documentation format originally conceived for Python (and also used in
+the Varnish distribution, as well as for formatting VMOD
+docs). `Sphinx <http://www.sphinx-doc.org/>`_ is used to render web
+pages from the RST sources.
+
+So you'll need to `learn markup with RST and Sphinx
+<http://www.sphinx-doc.org/en/stable/markup/index.html>`_; `install
+Sphinx <http://www.sphinx-doc.org/en/stable/install.html>`_ to test
+the rendering on your local system.
+
+Makefile
+--------
+
+Generation of web contents from the sources is driven by the ``Makefile``
+in the ``R1`` directory of the repo::
+
+  $ cd R1
+  $ make help
+  Please use `make <target>' where <target> is one of
+  html       to make standalone HTML files
+  dirhtml    to make HTML files named index.html in directories
+  singlehtml to make a single large HTML file
+  pickle     to make pickle files
+  json       to make JSON files
+  htmlhelp   to make HTML files and a HTML help project
+  qthelp     to make HTML files and a qthelp project
+  applehelp  to make an Apple Help Book
+  devhelp    to make HTML files and a Devhelp project
+  epub       to make an epub
+  latex      to make LaTeX files, you can set PAPER=a4 or PAPER=letter
+  latexpdf   to make LaTeX files and run them through pdflatex
+  latexpdfja to make LaTeX files and run them through platex/dvipdfmx
+  text       to make text files
+  man        to make manual pages
+  texinfo    to make Texinfo files
+  info       to make Texinfo files and run them through makeinfo
+  gettext    to make PO message catalogs
+  changes    to make an overview of all changed/added/deprecated items
+  xml        to make Docutils-native XML files
+  pseudoxml  to make pseudoxml-XML files for display purposes
+  linkcheck  to check all external links for integrity
+  doctest    to run all doctests embedded in the documentation (if enabled)
+  coverage   to run coverage check of the documentation (if enabled)
+
+Most of the time, you'll just need ``make html`` to test the rendering
+of your contribution.
+
+alabaster theme
+---------------
+
+We use the `alabaster theme <https://pypi.python.org/pypi/alabaster>`_,
+which you may need to add to your local Python installation::
+
+  $ sudo pip install alabaster
+
+We have found that you may need to link the alabaster package install
+directory to the directory where Sphinx expects to find themes. For
+example (on my machine), alabaster was installed into::
+
+  /usr/local/lib/python2.7/dist-packages/alabaster
+
+And Sphinx expects to find themes in::
+
+  /usr/share/sphinx/themes
+
+So to get the make targets to run successfully::
+
+  $ cd /usr/share/sphinx/themes
+  $ ln -s /usr/local/lib/python2.7/dist-packages/alabaster
+
+Test the rendering
+------------------
+
+Now you can edit contents in the website repo, and test the rendering
+by calling make targets in the ``R1`` directory::
+
+  $ cd $REPO/R1
+  $ make html
+  sphinx-build -b html -d build/doctrees   source build/html
+  Running Sphinx v1.2.3
+  loading pickled environment... done
+  building [html]: targets for 1 source files that are out of date
+  updating environment: 0 added, 1 changed, 0 removed
+  reading sources... [100%] tips/contribdoc/index
+  looking for now-outdated files... none found
+  pickling environment... done
+  checking consistency... done
+  preparing documents... done
+  writing output... [100%] tips/index
+  writing additional files... genindex search
+  copying static files... done
+  copying extra files... done
+  dumping search index... done
+  dumping object inventory... done
+  build succeeded.
+
+Send us a pull request
+----------------------
+
+When you have your contribution building successfully, send us a PR,
+we'll be happy to hear from you!

R1/source/tips/index.rst

@@ -3,32 +3,23 @@
 Tips & Tricks
 =============
 
-301/302 Redirects
------------------
+The :ref:`documentation in the standard distributions <docs>` includes
+the reference manual, user guides and tutorials, installation
+instructions and various other kinds of fundamental information.
 
-Synthetic responses can be used to generate 30x redirects, and
-the usual way is to stash the new location in req.http.something,
-and move that to resp.location in ``vcl_synth{}``.
+This is a space for nuggets of knowledge and solutions for specific
+requirements, how to get your Varnish deployment to run well, how to
+discover the cause of a problem and so forth.
 
-Here is a slightly neater way, exploiting the fact that ``return(synth())``
-takes two arguments::
+In part, this section is intended as a successor to the old  \ `wiki
+<https://www.varnish-cache.org/trac/wiki>`__, which had a wide range
+of useful hints, but much of which was written for older versions and
+is now outdated.
 
-	sub vcl_recv {
-	    if (req.url ~ "^/installation/ubuntu") {
-		return (synth(301, "/releases/install_ubuntu.html"));
-	    }
-	    if (req.url ~ "^/installation/debian") {
-		return (synth(302, "/releases/install_redhat.html"));
-	    }
-	}
-
-	sub vcl_synth {
-	    if (resp.status == 301 || resp.status == 302) {
-		set resp.http.location = resp.reason;
-		set resp.reason = "Moved";
-		return (deliver);
-	    }
-	}
+A Tips & Tricks sections thrives from everyone's active contribution,
+so please feel free to add your ideas, update the content, or to correct
+errors. The :ref:`HowTo <contribdoc>` section will help you get started.
 
 .. toctree::
-	:hidden:
+   contribdoc/index
+   vcl/index

R1/source/tips/vcl/index.rst

+.. _vcl:
+
+VCL Snippets
+============
+
+.. toctree::
+   redirect

R1/source/tips/vcl/redirect.rst

+301/302 Redirects
+-----------------
+
+Synthetic responses can be used to generate 30x redirects, and
+the usual way is to stash the new location in req.http.something,
+and move that to resp.location in ``vcl_synth{}``.
+
+Here is a slightly neater way, exploiting the fact that ``return(synth())``
+takes two arguments::
+
+	sub vcl_recv {
+	    if (req.url ~ "^/installation/ubuntu") {
+		return (synth(301, "/releases/install_ubuntu.html"));
+	    }
+	    if (req.url ~ "^/installation/debian") {
+		return (synth(302, "/releases/install_redhat.html"));
+	    }
+	}
+
+	sub vcl_synth {
+	    if (resp.status == 301 || resp.status == 302) {
+		set resp.http.location = resp.reason;
+		set resp.reason = "Moved";
+		return (deliver);
+	    }
+	}