Add site generation scripts

Things left for future work:
* Sort out a suitable host on which to publish this (QTQAINFRA-1211)
* Set up a routine site-publishing cron job (QTQAINFRA-1211)
* Make links of entries in some headers (QTQAINFRA-1212)

Task-number: QTQAINFRA-1173
Started-by: Louai Al-Khanji <louai.al-khanji@qt.io>
Change-Id: I7ee0c37e38cf30de52684ac80cb7848ec8712a0e
Reviewed-by: Frederik Gladhorn <frederik.gladhorn@qt.io>
Reviewed-by: Oswald Buddenhagen <oswald.buddenhagen@qt.io>

1 files changed, 149 insertions, 0 deletions

diff --git a/ReadMe.rst b/ReadMe.rst
new file mode 100644
index 0000000..830b3cc
--- /dev/null
+++ b/ReadMe.rst
@@ -0,0 +1,149 @@
+QUIP module maintenance
+=======================
+
+This module contains
+* The reStructuredText sources of all QUIPs (``quip-*.txt``)
+* The scripts to process them (``quips.pro`` and ``scripts/``)
+* A copy of Planet Qt as a sub-module
+
+See ``html/``, once generated, for further details, or the preamble
+for ``html/quip-000.html`` defined in ``scripts/gen-quip-0000.py`` for
+a preview of what this is all about.
+
+Generating HTML from QUIPs
+--------------------------
+
+You'll need this module checked out, along with its sub-module: see
+`Planet Qt and the template`_ for how to get Planet Qt checked out and
+up to date.
+
+You can generate the HTML using ``qmake`` and ``make``, provided you
+have (them and) both ``python`` and its ``docutils`` package
+installed.
+I recommend a shadow build: in some directory outside this source
+tree, run ``qmake`` on ``quips.pro`` in this directory; then, in the
+same directory, run ``make`` and it should generate a sub-directory
+``html/`` containing the generated HTML and symlinks to the supporting
+material from Planet Qt.
+You can then point a web browser at the result and review it.
+
+You can, of course, do the same in the source tree; you'll clutter it
+with the generated content.
+While ``.gitignore`` should save you from committing that, you can
+clean up more robustly in an out-of-source build.
+
+Checking
+~~~~~~~~
+
+It may be constructive to use checklink_ on the resulting HTML.
+On Debian, this is available for local use from the package named
+``w3c-linkcheker``; other systems probably have something similar.
+It can be run (be patient; it takes several minutes) as::
+
+ checklink -qbr html/quip-*.html
+
+If that finds any broken links, check to see whether they derive from
+the template (report to the planetqt maintainers) or from the source
+of the QUIP (``quip-*.txt``, report to the relevant QUIP's author).
+Some template links may use URLs without scheme,
+e.g. ``href="//www.qt.io/terms-conditions/"``, which checklink shall
+show as broken (since it's accessing links using ``file://``,
+implicitly); these are not normally a problem.
+
+.. _checklink: http://validator.w3.org/docs/checklink.html
+
+Planet Qt and the template
+--------------------------
+
+When you update this module, you should ``git submodule update
+--init`` to keep its ``planetqt/`` submodule in sync.
+This shall normally be on a revision for which the scripts are known
+to work.
+
+Updating
+~~~~~~~~
+
+In the ``planetqt/`` submodule, you can ``git checkout master`` and
+``git pull --ff-only`` to get an up-to-date version.
+This might work fine with the existing scripts and templates, in which
+case it's fine to ``git add planetqt`` in the super-module and commit.
+
+However, if ``planetqt/template.qt`` has changed, it's possible the
+scripts shall fail to generate ``template.html`` from it (in the build
+directory, if different from the source directory).
+The script first attempts this by applying ``scripts/template.diff``
+to produce ``scripts/template.html``; if this had succeeded, the
+result would have been moved to the build directory.
+When it fails, a partially-patched ``scripts/template.html`` should
+result in a ``scripts/template.rej`` file, containing the unapplied
+hunks from the patch.
+You'll need to manually adapt the patch's modifications to produce a
+sensible ``template.html`` (see below) based on the new
+``template.qt`` from Planet Qt.
+
+Once you have a usable ``scripts/template.html``, run::
+
+ $ diff -bu planetqt/template.qt scripts/template.html >scripts/template.diff
+
+You might then want to move your working ``template.html`` to safety,
+while you check that building works; your test build shall, otherwise,
+stomp your ``template.html`` in the process of generating the one it
+uses.
+If it all works nicely, commit your updated ``template.html`` along
+with the updated ``planetqt/``.
+
+How the template works
+~~~~~~~~~~~~~~~~~~~~~~
+
+The template file, ``template.html``, is mostly used verbatim in the
+generated web page for each QUIP, with a few tokens replaced, each of
+which starts with a % character.
+In particular, this means that any URLs in ``planetqt/template.qt``
+that contain %-encoded tokens (as part of the usual URL-encoding) need
+the % in each such token doubled up, to a %% that the reStructuredText
+engine shall convert back to a single % in the generated web page.
+
+The other tokens replaced are ``%(name)`` for various choices of
+``name``; most of these are set up in ``scripts/quip2html.py`` by
+``QuipWriter::interpolation_dict()`` adding entries to its ``subs``
+mapping.
+An entry for ``%(stylesheet)`` is generated from
+``QuipWriter::settings_default_overrides['stylesheet_path']`` and
+there may be more entries automagically added by the ``docutils``
+infrastructure, 'though we don't presently exercise these.
+
+Complications
+~~~~~~~~~~~~~
+
+When updating ``template.html`` from a new ``template.qt``, it is best
+to change as little as possible: keep the ``diff`` small so that
+``patch`` has a better chance of applying it.
+Generally, that means only changing what you must, nothing more.
+If you think the web-design of planetqt can be improved on, submit
+changes to it, don't complicate your differences from it with changes
+the next person updating this directory might not understand.
+
+Under ``planetqt/website`` there are assorted files that shall be
+referenced from your ``template.html``, expecting them to be in the
+same directory.
+There's also a sub-directory ``images/``.
+All of these need to be visible in the generated ``html/`` directory;
+this is arranged by a setup target in ``quips.pro`` which (to save a
+lot of repetition) uses ``scripts/setup.mk`` to drive creation of
+symlinks from ``html/`` to ``planetqt/website/``.
+You'll need to keep the ``WEBFILES`` and ``WEBDIRS`` lists up to date;
+each is a list of names, of files or directories respectively, within
+``planetqt/website`` that are needed by the template.
+
+If the new planetqt template contains a copyright notice, consult with
+planetqt's owners about whether they're happy to have the adapted
+template, without that notice, and accompanying linked content,
+released under this module's CC0 license.
+If they are, remove their license as part of adapting the template;
+otherwise, work out some sensible way to satisfy their needs within
+the framework of this module; you may need to find some other source
+than planetqt for templates and styling.
+
+Resist the temptation to replace the contents of planetqt/ with links
+to files on planet.qt.io: doing so would make it necessary to keep
+permanently in sync, instead of only updating when convenient.