[Checkins] SVN: grok/trunk/grokdocs/README.txt Update grokdocs docs.

[Uli Fouquet]

Log message for revision 86031:
  Update grokdocs docs.

Changed:
  U   grok/trunk/grokdocs/README.txt

-=-
Modified: grok/trunk/grokdocs/README.txt
===================================================================
--- grok/trunk/grokdocs/README.txt	2008-05-01 20:10:02 UTC (rev 86030)
+++ grok/trunk/grokdocs/README.txt	2008-05-01 20:22:24 UTC (rev 86031)
@@ -14,33 +14,50 @@
 Grok doc/ directory.
 
 
-How can I run `grokdocs`?
-=========================
+How to build documentation with `grokdocs`?
+===========================================
 
-`grokdocs` can be accessed by running 
+`grokdocs` can easily be accessed by running:: 
 
-	bin/grokdocs2html 
+   bin/grokdocs2html 
 
-or
+or::
 	
-	bin/grokdocs2latex
+   bin/grokdocs2latex
 
-from the Grok root source directory.
+from the Grok root source directory. It will parse all the .rst files
+in the doc/ directory of your local grok trunk.
 
-The results can be found by default in a newly created directory
-called `build` in the root of the Grok source directory.
+The results, a readily rendered static HTML site or a bunch of LaTeX
+files can be found afterwards by default in a newly created directory
+called `build/html/` or `build/latex` respectively in the root of the
+Grok source directory.
 
 To generate PDF files, just change to <Grok-Root>/build/latex and run
 
    make
 
-This should give you a tutorial, a reference and a grokdocs PDF file.
+This should give you a tutorial, a reference and a grokdocs PDF
+file, where the grokdocs.pdf includes all documents.
 
-You need LaTeX installed, to run pdflatex.
+Note: to generate PDF files you need a complete LaTeX installation.
 
 
+How to write Documentation
+==========================
+
+The Grok documentation held in the Grok SVN repository is limited to a
+set of certain documents. If a document is maintained in the SVN, the
+repository will be the authorative source, although it might be kept
+on the grok.zope.org website as well. Any changes to the website
+documents might be overriden when a new Grok release is published.
+
+On the other hand, the Grok repository won't contain documents, for
+which the website grok.zope.org is the authorative source. These
+documents should be changed on the website itself.
+
 What documents are handled by `grokdocs`?
-=========================================
+-----------------------------------------
 
 `grokdocs` takes only care for such documents, that have been agreed
 to be maintained in the Grok subversion repository. This means it
@@ -60,3 +77,20 @@
 
 Any other documentation parts should be done on the grok.zope.org
 website.
+
+How to write Grok documents
+---------------------------
+
+The grokdocs engine is a wrapper around the sphinx engine developed by
+Georg von Brandl for the general Python documentation.
+
+See the `sphinx site <http://sphinx.pocoo.org/>`_ for details.
+
+Sphinx uses ReStructuredText as document format. Furthermore it
+provides many extensions to the standard ReSTructuredText directives,
+so that you can markup special entities in a special way. This way you
+can tell sphinx, that something is a class, a function, a parameter or
+somthing else.
+
+See the already existing documents to learn how to write documentation
+with ReSTructuredText.