sandbox/README.txt

   1 ..                            -*- rst-mode -*-
   2
   3 =====================
   4  README: The Sandbox
   5 =====================
   6
   7 The Sandbox_ is a place to play around, to try out and share ideas. The
   8 `sandbox/`_ directory is a part of the Subversion repository but it isn't
   9 distributed as part of Docutils_ releases.
  10
  11 It's OK to make a mess in the Sandbox! But please, play nice.
  12
  13 A project-specific subdirectory should be created for each new project.
  14 Any developer who wants to play in the sandbox may create their own
  15 subdirectory (suggested name: SourceForge ID, or given name + family
  16 initial), but project directories are recommended over personal directories,
  17 which discourage collaboration.
  18
  19 For more information, please see the `Docutils Project Policies`_. The
  20 Sandbox is mirrored at the Docutils web site, so the `Docutils Web Site`_
  21 documentation applies as well.
  22
  23
  24 .. These links give readers a way to *go to* the sandbox:
  25 .. _sandbox:
  26 .. _sandbox/: ./
  27
  28 .. _Docutils: http://docutils.sourceforge.net/
  29 .. _Docutils Project Policies:
  30    http://docutils.sourceforge.net/docs/dev/policies.html#the-sandbox
  31 .. _Docutils Web Site: http://docutils.sourceforge.net/docs/dev/website.html
  32
  33
  34 Sandbox Projects
  35 ================
  36
  37 See the `sandbox/`_ directory for a complete list.
  38
  39 Some Sandbox projects, are also sorted into the `Docutils Link List`_.
  40
  41 .. _Docutils Link List: http://docutils.sf.net/docs/user/links.html
  42
  43 .. TODO: update the list of important sandbox projects (here or in the link
  44    list?)
  45
  46    The remainder of this section contained descriptions and links to obsolete
  47    or abadoned projects. Commented out because this give an impression of an
  48    attic instead of a place for experimenting.
  49
  50   Projects that are now implemented in Docutils
  51   ---------------------------------------------
  52
  53   * `<code-block-directive>`_ contains documentation, reasoning and
  54     experimental code for support of syntax highlight in Docutils.
  55     Preparational work for the `code`_ directive available since version 0.9.
  56
  57   * `LaTeX math for reST`_ by Jens J. Mortensen writes Math to
  58     LaTeX or MathML. This is the base of math_ support since version 0.8.
  59
  60   .. _code: docutils/docs/ref/rst/directives.txt#code
  61   .. _math: docutils/docs/ref/rst/directives.txt#math
  62   .. _LaTeX math for reST:
  63      http://docutils.sourceforge.net/sandbox/jensj/latex_math/
  64
  65   Documenting Python
  66   ------------------
  67
  68   Since Python 2.6, the markup used for the official `Python documentation`_
  69   is `reStructuredText`_, amended by custom directives. The Sphinx_ toolset is
  70   used to generate the HTML and LaTeX versions.
  71
  72   The sandbox contains some of the pervious work done on enabling Docutils to
  73   write the `"Documenting Python"`__ using rST.
  74
  75   __ http://docs.python.org/doc/doc.html
  76
  77   * `Edward Loper's sandbox
  78     <http://docutils.sf.net/sandbox/edloper/docpy/>`__.  The example
  79     "asyncore.rst" file was originally adapted by Steve Holden and Bill
  80     Sconce.
  81
  82   * `Dave Kuhlman's sandbox
  83     <http://docutils.sf.net/sandbox/dkuhlman/>`__ and `his homepage
  84     <http://www.rexx.com/~dkuhlman/rstpythonlatex_intro.html>`__.
  85
  86   * `docpy-writer <http://docutils.sf.net/sandbox/docpy-writer/>`__ was
  87     used for ctypes documentation.
  88
  89   .. _Python documentation: http://docs.python.org/
  90   .. _reStructuredText: http://docutils.sf.net/rst.html
  91   .. _Sphinx: http://sphinx.pocoo.org/
  92
  93   Project Infrastructure
  94   ----------------------
  95
  96   `docutils-update <infrastructure/docutils-update>`_ is a script that
  97   was installed as a cron job on BerliOS.de to automatically update the
  98   Docutils `web site`_ whenever the SVN files change.  Any .html
  99   document with a corresponding .txt file is regenerated whenever the
 100   .txt file changes.
 101
 102   .. _web site: http://docutils.sf.net/docs/dev/website.html