[Checkins] SVN: Sandbox/ulif/grok-reference-with-rest2/doc/grokref/ Updated documentation.

Uli Fouquet uli at gnufix.de
Thu Jan 10 19:10:10 EST 2008


Log message for revision 82791:
  Updated documentation.

Changed:
  A   Sandbox/ulif/grok-reference-with-rest2/doc/grokref/HACKING.txt
  U   Sandbox/ulif/grok-reference-with-rest2/doc/grokref/README.txt

-=-
Added: Sandbox/ulif/grok-reference-with-rest2/doc/grokref/HACKING.txt
===================================================================
--- Sandbox/ulif/grok-reference-with-rest2/doc/grokref/HACKING.txt	                        (rev 0)
+++ Sandbox/ulif/grok-reference-with-rest2/doc/grokref/HACKING.txt	2008-01-11 00:10:09 UTC (rev 82791)
@@ -0,0 +1,47 @@
+=====================
+Grokref: why and how?
+=====================
+
+What is so special about grok reference documentation?
+------------------------------------------------------
+
+It is special, because some 'tags' (i.e. `roles` and `directives`) are
+used, that are not supported by standard Python ``docutils``. The
+``docutils`` package is a tool to create HTML and other output formats
+from ReST.
+
+In the reference are roles and directives used, that are used also in
+the standard Python source code documentation (starting with Python
+2.6) but not supported by the standard ``docutils`` package. Those
+roles and directives include such as `mod`, `func` etc. to describe
+special entities of APIs.
+
+Unfortunately, the ``sphinx`` package, which is part of the standard
+Python toolchain, currently only supports the Python source code tree
+itself for generation of HTML and other output. Other ReST document
+collections cannot be used with it out-of-the-box. Fir example
+directory names are hardcoded in `sphinx` and it needs at least Python
+2.5 to generate reference documentation.
+
+
+What is the purpose of ``grokref``?
+-----------------------------------
+
+Grokref delivers support for the extra roles and directives used in
+the standard Python documentation, without the need to use the whole
+sphinx toolchain. Just import `directives_plain` and `roles_plain`
+from the `extensions/` directory, and your docutils parser understands
+roles and directives like `mod`, `function` etc. See bottom of
+README.txt for a list of additionally supported roles and directives.
+
+The tool `grokref2html` is an example, how to write a publisher, that
+supports the additional roles and directives, to create HTML
+documents. 
+
+It is written in a way, so that other references could be generated as
+well.
+
+Grokref tries to provide the full set of roles and directives as is
+provided by the standard Python documentation. The output, however,
+will be different from what you might expect, if you have seen the
+``sphinx`` output before.

Modified: Sandbox/ulif/grok-reference-with-rest2/doc/grokref/README.txt
===================================================================
--- Sandbox/ulif/grok-reference-with-rest2/doc/grokref/README.txt	2008-01-10 23:48:33 UTC (rev 82790)
+++ Sandbox/ulif/grok-reference-with-rest2/doc/grokref/README.txt	2008-01-11 00:10:09 UTC (rev 82791)
@@ -5,8 +5,6 @@
 Generate reference documentation in various formats from ReStructured
 Text (ReST) sources.
 
-What is so special about grok reference documentation?
-------------------------------------------------------
 
 The grok reference documentation can be found in the `doc/reference`
 subdirectory of every source distribution of Grok. The sources can be
@@ -14,50 +12,29 @@
 
 The reference consists of a set of ReStructured Text source files.
 
-It is special, because some 'tags' are used, that are not supported by
-standard Python ``docutils``. The ``docutils`` package is a tool to
-create HTML and other output formats from ReST.
 
-In the reference are roles and directives used, that are used also in
-the standard Python source code documentation (starting with Python
-2.6) but not in the standard ``docutils`` package. Unfortunately, the
-``sphinx`` package, which is part of the standard Python toolchain,
-currently only supports the Python source code tree for generation of
-HTML and other output. Directory names are hardcoded and everything
-needs at least Python 2.5 to generate reference documentation with the
-``sphinx`` package.
-
-
-What is the purpose of ``grokref``?
------------------------------------
-
-``grokref`` is a package to add support for the special roles and
-directives mentioned above but without the need to use the sphinx
-package. It allows generation of the Grok reference manual in HTML and
-PDF (LaTeX) format.
-
-It is written in a way, so that other references could be generated as
-well.
-
-Grokref tries to provide the full set of roles and directives as is
-provided by the standard Python documentation. The output, however,
-will be different from what you might expect, if you have seen the
-``sphinx`` output before.
-
-
 How can I generate HTML from the ReST sources?
 ----------------------------------------------
 
 After running ``buildout`` in the grok ``bin`` directory, there should
 be a new script called ``grokref2html``. This script can be called
-with a ReST source file as argument::
+with a source directory as argument::
 
-   $ bin/grokref2html doc/reference/index.rst
+   $ bin/grokref2html doc/reference
 
-This will ouput HTML to the commandline (subject to change).
+This will ouput HTML files (one for each .rst file found in the
+directory) in the source directory.
 
-Run::
+To generate the output in a different directory, just pass the target
+directory as additional parameter::
 
+   $ bin/grokref2html doc/reference ~/targetdir
+
+The destination directory must exist before.
+
+There are plenty of options for the reference building process, which
+are listed, if you run::
+
    $ bin/grokref2html --help
 
 for a complete list of available options.
@@ -69,38 +46,188 @@
 
 Just write normal ReST sources.
 
-You can (and should) use the following additional roles and directives
-to better describe the things you describe:
+Primers for writing restructured text documents are available at
 
+  http://docutils.sourceforge.net/rst.html
 
-Additional value substitutions:
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+and::
 
-The following keys can be used in reference documents by enclosing
-them in pipe characters (`|`). They will be substituted by values
-defined in the ``ReferenceProducer``.
+  http://docs.python.org/dev/documenting/rest.html
 
+The document you are reading, is a ReST file as well, of course.
+
+You can (and should), however, use the following additional roles and
+directives to better describe the things you describe:
+
+
+Substitutions, Roles and Directives supported by grokref:
+---------------------------------------------------------
+
+The following roles, directives and substitutions are supported by
+grokref but not by the standard docutils tools.
+
+Additional Default Substitutions:
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Substitutions in the `doctools` sense are keywords, which are written
+enclosed in pipe characters (`|`) in ReST sources and which are
+replaced by certain values during parsing and document generation. You
+can therefore think of substitutions as of placeholders.
+
+Typical substitutions are `date`, `time` and `version`. Unfortunately,
+the values of those substitutions are not defined by default and its
+use leads to errors and warnings.
+
+To define a substitution, you can use ReST as shown on:
+
+  http://docutils.sourceforge.net/docs/ref/rst/substitutions.html
+
+If you use a `ReferenceReader` from the `grokref.grok2html` modules,
+the following substitutions are set.
+
+You can also use an instance of ``ReferenceProducer`` (which uses
+`ReferenceReader` by default) and set the instances `version`,
+`release` and `today` attributes, whose values will then show up in
+the generated documents.
+
 * ``version``:
 
-  The version of grok that is documented.
+  The version of grok that is documented. For example `0.11`.
 
 * ``release``:
 
-  The release that is documented.
+  The release that is documented. For example `0.11a`.
 
 * ``today``:
 
-  The date of today.
+  The date of today, i.e. the day you generate documentation.
 
 
 Additional directives:
 ~~~~~~~~~~~~~~~~~~~~~~
 
+Directives are written in ReST sources with a directive name followed
+by two semicolons. Normally they are preceeded by two dots and a
+space. Directives define a special 'environment', to mark the
+following text (as long as it is indented) as one compound
+unit. 
+
+Typical directives (provided by the standard `docutils`) include
+`caution` to mark a block of text with warnings, `note`, `image` or
+`sidebar`. Usually directives mark complete blocks of text, while
+roles only mark one or a few words. If you want to mark the word
+`myfunc` as a function, use a role. If you want to describe the
+function extensively, with all parameters and return values, use a
+directive.
+
+Directives not provided by standard `docutils` but by `grokref` and
+`sphinx`:
+
+Python Directives
++++++++++++++++++
+
+* ``attribute``:
+
+  To describe an attribute of a class.
+
+* ``class``:
+
+  To describe a Python class.
+
+* ``data``:
+
+  To describe some data extensively.
+
+* ``exception``:
+
+  To describe an exception type.
+
 * ``function``:
 
-  To describe functions and methods with their signature.
+  To describe functions with their signature.
 
+* ``method``:
 
+  To describe a class method.
+
+Generic Directives 
+++++++++++++++++++
+
+* ``cmdoption``:
+
+  To describe command options of a program.
+
+* ``envvar``:
+
+  To describe environment variables.
+
+* ``decribe``:
+
+  To describe something that describes something.
+
+
+Special Directives:
++++++++++++++++++++
+
+* ``toctree``:
+
+  Currently disabled.
+
+  The `toctree` directive creates a table of contents of given ReST
+  files, which are given as arguments. A typical toctree definition
+  might look like this::
+
+    .. toctree::
+       :maxdepth: 2
+
+       file1.rst
+       file2.rst
+       foo.rst
+
+  The option `maxdepth` (default: 0 == no limit)
+  determines the maximum depth of the toctree to be generated.
+
+  The filename entries will then be replaced by the headings (TOCs) of
+  the appropriate files.
+
+  .. note::
+
+    This directive is currently accepted by grokref, but not
+    processed. A toctree will therefore not show up in your documents.
+
+* ``seealso``:
+
+  This directive works like a `note` or `caution` amonition. There is
+  no special handling of references in `seealso`` directives.
+
+* ``versionadded``:
+
+  This directive indicates, that something was added during a certain
+  release. 
+
+  It requires a version number as first argument and prints then the
+  rest of the contents.
+
+  A typical usage would be::
+
+    .. versionadded:: 0.12
+
+    Added in version 0.12. Don't use clubs in prior versions.
+
+* ``versionchanged``:
+
+  This directive indicates, that something (especially a signature or
+  similar) changed during version changes. See ``versionadded``.
+
+* ``deprecated``:
+
+  This directive indicates, that something, a function, class or
+  similar, is deprecated. It also requires a version number and an
+  explanatory text.
+
+  See ``versionadded`` for details.
+
+
 Additional roles (general):
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -187,8 +314,3 @@
 sufficient to include the roles and directives from the ``extensions``
 directory.
 
-Note, that you also need a ``translator`` to translate the special
-entitites supported by grokref into your special output format. Some
-examples can be found in ``translators.py`` in the `extensions`
-directory.
-



More information about the Checkins mailing list