[Checkins] SVN: grok/trunk/doc/ Add new documentation files.
Jan-Wijbrand Kolman
janwijbrand at gmail.com
Thu May 1 06:27:52 EDT 2008
Log message for revision 85977:
Add new documentation files.
Changed:
A grok/trunk/doc/ACKS.txt
A grok/trunk/doc/README.rst
A grok/trunk/doc/bugs.rst
A grok/trunk/doc/changes.rst
A grok/trunk/doc/contents.rst
A grok/trunk/doc/copyright.rst
A grok/trunk/doc/docindex.template
A grok/trunk/doc/license.rst
A grok/trunk/doc/resources/
-=-
Copied: grok/trunk/doc/ACKS.txt (from rev 85967, grok/branches/ulif-grokdocs/doc/ACKS.txt)
===================================================================
--- grok/trunk/doc/ACKS.txt (rev 0)
+++ grok/trunk/doc/ACKS.txt 2008-05-01 10:27:51 UTC (rev 85977)
@@ -0,0 +1,23 @@
+Contributors to the Grok Documentation
+======================================
+
+This section lists people who have contributed in some way to the Grok
+documentation. It is probably not complete -- if you feel that you or
+anyone else should be on this list, please let us know (send email to
+grok-dev at zope.org), and we'll be glad to correct the problem.
+
+.. acks::
+
+ * Darryl Cousins
+ * Kushal Das
+ * Martijn Faassen
+ * Uli Fouquet
+ * Jim Fulton
+ * Jan-Wijbrand Kolman
+ * Luis de la Parra
+ * Luciano Ramalho
+ * Lennart Regebro
+ * Brandon Craig Rhodes
+ * Kevin Teague
+ * Sebastian Ware
+ * Philipp von Weitershausen
Copied: grok/trunk/doc/README.rst (from rev 85967, grok/branches/ulif-grokdocs/doc/README.rst)
===================================================================
--- grok/trunk/doc/README.rst (rev 0)
+++ grok/trunk/doc/README.rst 2008-05-01 10:27:51 UTC (rev 85977)
@@ -0,0 +1,101 @@
+*********************
+About these documents
+*********************
+
+These documents are generated from `reStructuredText
+<http://docutils.sf.net/rst.html>`_ sources by *Sphinx*, an excellent
+document processor specifically written for the Python documentation
+by Georg Brandl and contributors.
+
+In the online version of these documents, you can submit comments and suggest
+changes directly on the documentation pages.
+
+Development of this documentation and its toolchain takes place on the
+grok-dev at zope.org mailing list. We're always looking for volunteers
+wanting to help with the docs, so feel free to send a mail there!
+
+Many thanks go to:
+
+* the `docutils <http://docutils.sf.net/>`_ project for creating
+ reStructuredText and the docutils suite;
+* Georg Brandl for his `sphinx` package.
+
+See :ref:`reporting-bugs` for information how to report bugs in Python itself.
+
+.. including the ACKS file here so that it can be maintained separately
+.. include:: ACKS.txt
+
+It is only with the input and contributions of the Grok community
+that Grok has so much documentation -- Thank You!
+
+
+The Grok documentation toolchain
+================================
+
+Grok now makes use of the ``sphinx`` package, which was written by
+Georg Brandl and volunteers, to generate the official Python
+documentation. Sphinx is able to generate HTML as well as LaTeX and
+HTMLHelp formats. The latter is currently not supported by grokdocs.
+
+The ``grokdocs`` module provides wrappers for ``sphinx``.
+
+
+How can I generate nice HTML/LaTeX/PDF documentation for Grok?
+--------------------------------------------------------------
+
+
+If you have run ``bin/buildout``, than you're nearly finished. This
+will generate some scripts in the ``bin/`` directory. Just run::
+
+ $ bin/grokdocs2html
+
+to generate the HTML documentation. The docs will be placed in
+
+ docs/build/html/
+
+For LaTeX/PDF docs you must have LaTeX and ``pdflatex`` installed. If
+you want PDF docs, you have to perform two steps.
+
+1) Run::
+
+ $ bin/grokdocs2latex
+
+ which will generate .tex files and appropriate Makefiles in
+ ``docs/build/latex``.
+
+2) Then change to ``docs/buid/latex`` and do::
+
+ $ make
+
+The latter will run `pdflatex` to generate three documents:
+
+1) The Tutorial (``tutorial.pdf``)
+
+2) The Reference (``reference.pdf``)
+
+3) The whole documentation (``grokdocs.pdf``)
+
+which can be found in ``docs/build/latex``.
+
+Any warnings during the document processing can be ignored for the
+time being.
+
+You can run each of the scripts with the `-h` option to see other
+available options. The new documentation toolchain is basically able
+to build **any** documentation, not just the Grok documentation.
+
+
+How to tweak the layout/settings of the documentation toolchain
+---------------------------------------------------------------
+
+The general settings of documentation generated by ``sphinx`` and
+``grokdocs`` are settable in a file ``conf.py`` which must be in the
+source root directory of your docs. Have a look at ``docs/conf.py``
+for deeper insights.
+
+The structure of the HTML entry page is defined in
+``build/docindex.template``, which is a template for the Jinja
+templating engine used by Sphinx.
+
+The layout details are defined in ``docs/.static/grok.css``.
+
Copied: grok/trunk/doc/bugs.rst (from rev 85967, grok/branches/ulif-grokdocs/doc/bugs.rst)
===================================================================
--- grok/trunk/doc/bugs.rst (rev 0)
+++ grok/trunk/doc/bugs.rst 2008-05-01 10:27:51 UTC (rev 85977)
@@ -0,0 +1,64 @@
+.. _reporting-bugs:
+
+**********************
+Reporting Bugs in Grok
+**********************
+
+Grok aims to become a mature framework and tries to earn reputation
+for stability. In order to maintain this reputation, the developers
+would like to know of any deficiencies you find in Grok.
+
+If you find errors in the documentation, you can correct it yourself
+on the Grok website http://grok.zope.org/ . You only need to register
+with the website for that, which is necessary to block spammers. On
+some pages you then can use the "Add a comment" feature of the
+relevant page.
+
+All other bug reports should be submitted via the Grok Bug Tracker
+(https://bugs.launchpad.net/grok/). The bug tracker offers a Web form
+which allows pertinent information to be entered and submitted to the
+developers.
+
+The first step in filing a report is to determine whether the problem
+has already been reported. The advantage in doing so, aside from
+saving the developers time, is that you learn what has been done to
+fix it; it may be that the problem has already been fixed for the next
+release, or additional information is needed (in which case you are
+welcome to provide it if you can!). To do this, search the bug
+database using the search box on the top of the page or by clicking on
+"List all open bugs".
+
+If the problem you're reporting is not already in the bug tracker, go
+back to the Grok Bug Tracker and click the red "Report a bug" box on
+the right. If you don't already have a launchpad account, you will be
+asked to complete the registration by giving an e-mail address and
+following the steps mailed to you. Complete the registration process.
+Otherwise, if you're not logged in, enter your credentials and select
+"Log In". It is not possible to submit a bug report anonymously.
+
+Being now logged in, you can submit a bug. You will be asked a number
+of questions.
+
+For the "Summary" field, enter a *very* short description of the
+problem; less than ten words is good. In the "Further Information"
+field, describe your problem as accurate as possible. A good
+description will enables the developers to reproduce your
+problem. Name also the version of grok/grokproject you used.
+
+Each bug report will be assigned to a developer who will determine
+what needs to be done to correct the problem. You will receive an
+update each time action is taken on the bug.
+
+.. seealso::
+
+ `How to Report Bugs Effectively
+ <http://www.chiark.greenend.org.uk/~sgtatham/bugs.html>`_ Article
+ which goes into some detail about how to create a useful bug
+ report. This describes what kind of information is useful and why
+ it is useful.
+
+ `Bug Writing Guidelines
+ <http://www.mozilla.org/quality/bug-writing-guidelines.html>`_
+ Information about writing a good bug report. Some of this is
+ specific to the Mozilla project, but describes general good
+ practices.
Copied: grok/trunk/doc/changes.rst (from rev 85967, grok/branches/ulif-grokdocs/doc/changes.rst)
===================================================================
--- grok/trunk/doc/changes.rst (rev 0)
+++ grok/trunk/doc/changes.rst 2008-05-01 10:27:51 UTC (rev 85977)
@@ -0,0 +1,7 @@
+
+.. include:: upgrade.txt
+
+.. _changes:
+.. include:: ../CHANGES.txt
+
+
Copied: grok/trunk/doc/contents.rst (from rev 85967, grok/branches/ulif-grokdocs/doc/contents.rst)
===================================================================
--- grok/trunk/doc/contents.rst (rev 0)
+++ grok/trunk/doc/contents.rst 2008-05-01 10:27:51 UTC (rev 85977)
@@ -0,0 +1,17 @@
+===========================
+Grok Documentation Contents
+===========================
+
+.. toctree::
+ :maxdepth: 2
+
+ changes.rst
+ about.rst
+ tutorial.rst
+ reference/index.rst
+ minitutorials/index.rst
+ naming_conventions.rst
+
+ bugs.rst
+ license.rst
+ copyright.rst
Copied: grok/trunk/doc/copyright.rst (from rev 85967, grok/branches/ulif-grokdocs/doc/copyright.rst)
===================================================================
--- grok/trunk/doc/copyright.rst (rev 0)
+++ grok/trunk/doc/copyright.rst 2008-05-01 10:27:51 UTC (rev 85977)
@@ -0,0 +1,11 @@
+*********
+Copyright
+*********
+
+Grok and this documentation is:
+
+Copyright © 2006-2008 Zope Community and Contributors. All rights reserved.
+
+----------
+
+See: :ref:`license` for complete license and permissions information.
Copied: grok/trunk/doc/docindex.template (from rev 85967, grok/branches/ulif-grokdocs/doc/docindex.template)
===================================================================
--- grok/trunk/doc/docindex.template (rev 0)
+++ grok/trunk/doc/docindex.template 2008-05-01 10:27:51 UTC (rev 85977)
@@ -0,0 +1,65 @@
+ <p><strong>Parts of the documentation:</strong></p>
+ <table class="contentstable" align="center"><tr>
+ <td width="50%">
+ <p class="biglink"><a class="biglink" href="{{ pathto("changes") }}"
+ >What's new in Grok {{ version }}?</a><br>
+ <span class="linkdescr">changes during the releases</span></p>
+
+ <p class="biglink"><a class="biglink" href="{{ pathto("tutorial") }}"
+ >Tutorial</a><br>
+ <span class="linkdescr">Get started with Grok</span></p>
+
+ <p class="biglink"><a class="biglink" href="{{ pathto("minitutorials/index") }}"
+ >Grok HOWTOS</a><br>
+ <span class="linkdescr">in-depth documents on specific topics</span></p>
+
+ </td><td width="50%">
+
+ <p class="biglink"><a class="biglink" href="{{ pathto("about") }}"
+ >About Grok</a><br>
+ <span class="linkdescr">now even Cavemen can use Zope 3</span></p>
+
+ <p class="biglink"><a class="biglink" href="{{ pathto("reference/index") }}">The Grok Reference</a><br>
+ <span class="linkdescr">describes syntax and package elements</span></p>
+
+ <p class="biglink"><a class="biglink" href="{{ pathto("naming_conventions") }}">Naming Conventions</a><br>
+ <span class="linkdescr">how to name your stuff correctly</span></p>
+
+
+ </td></tr>
+ </table>
+ <p><strong>Indices and tables:</strong></p>
+ <table class="contentstable" align="center"><tr>
+ <td width="50%">
+ <p class="biglink"><a class="biglink" href="{{ pathto("contents") }}">Complete Table of Contents</a><br>
+ <span class="linkdescr">lists all sections and subsections</span></p>
+<!--
+ <p class="biglink"><a class="biglink" href="{{ pathto("search") }}">Search page</a><br>
+ <span class="linkdescr">search this documentation</span></p>
+-->
+ </td><td width="50%">
+ <p class="biglink"><a class="biglink" href="{{ pathto("genindex") }}">General Index</a><br>
+ <span class="linkdescr">all functions, classes, terms</span></p>
+ </td></tr>
+ </table>
+
+ <p><strong>Meta information:</strong></p>
+ <table class="contentstable" align="center"><tr>
+ <td width="50%">
+
+ <p class="biglink"><a class="biglink" href="{{ pathto("bugs") }}"
+ >Reporting bugs</a><br>
+
+ <p class="biglink"><a class="biglink" href="{{ pathto("README") }}"
+ >About the documentation</a><br>
+
+ </td><td width="50%">
+
+ <p class="biglink"><a class="biglink" href="{{ pathto("license") }}"
+ >License</a><br>
+
+ <p class="biglink"><a class="biglink" href="{{ pathto("copyright") }}"
+ >Copyright</a><br>
+
+ </td></tr>
+ </table>
Copied: grok/trunk/doc/license.rst (from rev 85967, grok/branches/ulif-grokdocs/doc/license.rst)
===================================================================
--- grok/trunk/doc/license.rst (rev 0)
+++ grok/trunk/doc/license.rst 2008-05-01 10:27:51 UTC (rev 85977)
@@ -0,0 +1,62 @@
+.. _license:
+
+***********
+The License
+***********
+
+Zope Public License (ZPL) Version 2.1
+-------------------------------------
+
+A copyright notice accompanies this license document that
+identifies the copyright holders.
+
+This license has been certified as open source. It has also
+been designated as GPL compatible by the Free Software
+Foundation (FSF).
+
+Redistribution and use in source and binary forms, with or
+without modification, are permitted provided that the
+following conditions are met:
+
+1. Redistributions in source code must retain the
+ accompanying copyright notice, this list of conditions,
+ and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the accompanying
+ copyright notice, this list of conditions, and the
+ following disclaimer in the documentation and/or other
+ materials provided with the distribution.
+
+3. Names of the copyright holders must not be used to
+ endorse or promote products derived from this software
+ without prior written permission from the copyright
+ holders.
+
+4. The right to distribute this software or to use it for
+ any purpose does not give you the right to use
+ Servicemarks (sm) or Trademarks (tm) of the copyright
+ holders. Use of them is covered by separate agreement
+ with the copyright holders.
+
+5. If any files are modified, you must cause the modified
+ files to carry prominent notices stating that you changed
+ the files and the date of any change.
+
+Disclaimer
+
+ THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS ''AS IS''
+ AND ANY EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT
+ NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY
+ AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN
+ NO EVENT SHALL THE COPYRIGHT HOLDERS BE
+ LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
+ EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+ LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+ LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+ HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+ CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
+ OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+ SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH
+ DAMAGE.
+
+
Copied: grok/trunk/doc/resources (from rev 85967, grok/branches/ulif-grokdocs/doc/resources)
More information about the Checkins
mailing list