Mailing-List: contact commits-help@logging.apache.org; run by ezmlm
Precedence: bulk
Reply-To: dev@logging.apache.org
Content-Type: text/plain; charset="us-ascii"
MIME-Version: 1.0
Content-Transfer-Encoding: 7bit
From: ihabunek@apache.org
To: commits@logging.apache.org
Subject: [1/2] git commit: Updated README for docs
Message-Id: <20121217160503.5C5D581DC87@tyr.zones.apache.org>
Date: Mon, 17 Dec 2012 16:05:03 +0000 (UTC)

Updated Branches:
  refs/heads/docs 4780fc1e6 -> f6eb76ddc


Updated README for docs


Project: http://git-wip-us.apache.org/repos/asf/logging-log4php/repo
Commit: http://git-wip-us.apache.org/repos/asf/logging-log4php/commit/f6eb76dd
Tree: http://git-wip-us.apache.org/repos/asf/logging-log4php/tree/f6eb76dd
Diff: http://git-wip-us.apache.org/repos/asf/logging-log4php/diff/f6eb76dd

Branch: refs/heads/docs
Commit: f6eb76ddc82b0d952c08398f626b47f4045f17c2
Parents: 85ad41b
Author: Ivan Habunek <ivan.habunek@gmail.com>
Authored: Mon Dec 17 17:04:50 2012 +0100
Committer: Ivan Habunek <ivan.habunek@gmail.com>
Committed: Mon Dec 17 17:04:50 2012 +0100

----------------------------------------------------------------------
 docs/README.rst |   93 +++++++++++++++++++++++++++++++++++++++++--------
 1 files changed, 77 insertions(+), 16 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/logging-log4php/blob/f6eb76dd/docs/README.rst
----------------------------------------------------------------------
diff --git a/docs/README.rst b/docs/README.rst
index 7cb1e92..4363f3c 100644
--- a/docs/README.rst
+++ b/docs/README.rst
@@ -4,26 +4,88 @@ Apache log4php documentation
 
 This directory contains the documentation for Apache log4php.
 
-The documentation is in `reStructuredText <http://docutils.sourceforge.net/rst.html>`_ format and 
-can be viewed using any text editor. Conversion to other formats, such as html, epub and pdf is 
-achieved by using the `Sphinx documentation system <http://sphinx-doc.org/>`_, and requires 
-`Python <http://python.org/>`_.
+The documentation is in reStructuredText_ format and can be viewed using any
+text editor. Conversion to other formats, such as html, epub and pdf is achieved
+by using the Sphinx_ documentation system, and requires Python_.
 
-To render the documentation to HTML:
+.. _reStructuredText: http://docutils.sourceforge.net/rst.html
+.. _Sphinx: http://sphinx-doc.org/
+.. _Python: http://www.python.org/
 
-* install Sphinx (using ``sudo pip install Sphinx`` or some other method)
-* using a virtual environment is recommended
-* while in the ``docs`` directory, run ``make html``
+Setting up
+----------
+It's recommended to have the latest version of Python 2.7.x, along with pip and
+virtualenv. If you're not sure how to set this up, there's a good guide for all
+platforms `here <https://python-guide.readthedocs.org/en/latest/>`_.
 
-The documentation will be rendered to ``_build/html/``.
+First, create a virutal environment in _env directory and activate it.
 
-Theme notes
-===========
+Linux:
+
+.. code-block:: bash
+
+    virtualenv _env
+    source _env/bin/activate
+
+Windows:
+
+.. code-block:: bat
+
+    virtualenv _env
+    _env\Scripts\activate.bat
+
+The requirements are listed in `requirements.txt` so it's easy to install them:
+
+.. code-block:: bash
+
+    pip install -r requirements.txt
+
+You're now set up for generating docs.
 
-Apache log4php uses a custom Sphinx theme called (very imaginatively) `log4php`. The theme is 
+Generating
+----------
+Running `make help` displays all possible targets:
+
+.. code-block:: none
+
+    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
+      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
+      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
+      linkcheck  to check all external links for integrity
+      doctest    to run all doctests embedded in the documentation (if enabled)
+
+Most common target is ``make html`` which generates HTML documentation into
+``_build/html`` directory.
+
+Generating PDF (`latexpdf` target) is done by generating latex and converting it
+to PDF. This step required LaTeX. On debian based systems, it can be installed
+by running:
+
+.. code-block:: bash
+
+    apt-get install texlive-full
+
+Theme notes
+-----------
+Apache log4php uses a custom Sphinx theme called (very imaginatively) `log4php`. The theme is
 located under ``_theme/log4php``.
 
-One specific hack which this theme provides is making html tabs which are most frequently used 
+One specific hack which this theme provides is making html tabs which are most frequently used
 for displaying XML and PHP variants of the same configuration code.
 
 To generate tabs, do the following:
@@ -35,10 +97,9 @@ To generate tabs, do the following:
         .. rubric:: XML format
         .. code-block:: xml
 
-        <div id="xml_code">...</div>
+            <div id="xml_code">...</div>
 
         .. rubric:: PHP format
         .. code-block:: php
 
-        array("php_code" => array(...))
-
+            array("php_code" => array(...))