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