=======
Read me
=======

This repository contains all tools required to build the Apache zeta
Components website. It is based on a GNU make script and using WCV__ for the
HTML generation.

__ http://web-content-viewer.org/

Usage
=====

To regenerate the website just execute::

    make website

All required steps will be performed. Afterwards the generated website is
available in ``htdocs`` and can be committed.

Revertig "unchanged" files
==========================

When rebuilding the website, HTML files are commonly generated that only have
changes due to date/time or author updates. The command::

    make revert-empty

applies a heuristic to identify most of these and automatically revert them.
**Please make sure to always use this make target before commiting changes to
htdocs/, in order to generate readable diffs.**

Doc rebuilding
==============

The website contains two kinds of documentation:

- The tutorials
- The API documentation

They are generated separately:

The API documentation
---------------------

The API docs are build using *phpdoc* and currently requires about 2.5GB of
free memory to build. By default the API documentation is build for ``trunk/``
when calling ``make phpdoc``. You can pass specific release information to the
build process like this::

    ZETA_BASE=/path/to/zeta/2023.42 make -e phpdoc

This will build an archive containing the API documentation and move it to the
correct location in the content folder. You can just commit the content folder
afterwards.

To make the API documentation available for the website you also need to call
``make extract-phpdoc`` with the same ``ZETA_BASE`` path. This will also be
done using ``make docs`` (see below).

The tutorials
-------------

The tutorials are just copied from the zeta docs sections and made available on
the website. This can be done by using ``make tutorials``. If you want to
execute this for a specific release instead of trunk, pass a ``ZETA_BASE``
environment variable to the script like shown above.

Both, the extraction of the API documentation, and the copying of the tutorials
is performed by ``make docs``.

Content editing
===============

You can edit all the contents in the ``content/`` folder. Those are just ReST
files. Be sure to call ``make website`` afterwards and commit the changes.
Rebuilding the website might take some time.

If you add new contents, remember to adapt the ``.index.xml`` in the respective
directory accordingly.

Writing news
------------

To write news, just create a new ReST file in ``content/news/``, following the
naming scheme of existing blog posts, and reference it in
``content/news/.blog.xml``. Remember to include an ``abstract`` or
``description`` field list element, which defines the text occurring on the blog
overview page.

Releasing
=========

To rebuild everything for a release you probably want to execute the following
commands::

    # Building the API docs, requires lots of memory, maybe execute on a
    # dedicated server.
    ZETA_BASE=/path/to/zeta/2023.42 make -e phpdoc

    # Extracting the new docs
    ZETA_BASE=/path/to/zeta/2023.42 make -e docs

    # Regenerating the HTML
    make website

    # Commit the new stuff
    svn ci


..
   Local Variables:
   mode: rst
   fill-column: 79
   End: 
   vim: et syn=rst tw=79