You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@logging.apache.org by ih...@apache.org on 2013/12/14 15:56:57 UTC
[11/23] git commit: Updated README for docs
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/develop
Commit: f6eb76ddc82b0d952c08398f626b47f4045f17c2
Parents: 85ad41b
Author: Ivan Habunek <iv...@gmail.com>
Authored: Mon Dec 17 17:04:50 2012 +0100
Committer: Ivan Habunek <iv...@gmail.com>
Committed: Mon Dec 17 17:04:50 2012 +0100
----------------------------------------------------------------------
docs/README.rst | 93 +++++++++++++++++++++++++++++++++++++++++++---------
1 file 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(...))