sandbox/docpy-writer/README.txt

   1 ====================================
   2  Docutils_ for python documentation
   3 ====================================
   4
   5 :Contact: grubert@users.sourceforge.net
   6 :Revision: $Revision$
   7 :Date: $Date$
   8 :Copyright: This document has been placed in the public domain.
   9
  10 This tried, at a time when texinfo was used, to explore the posibilities to use
  11 docutils as format for python library documentation as specified in
  12 `Documenting Python`_ .
  13
  14 This version is based on a script from Greg Ward, hacked by Thomas Heller.
  15
  16 There is also
  17
  18 * `Edward Loper's sandbox
  19   <http://docutils.sf.net/sandbox/edloper/docpy/>`__.  The example
  20   "asyncore.rst" file was originally adapted by Steve Holden and Bill
  21   Sconce.
  22
  23 * `Dave Kuhlman's sandbox
  24   <http://docutils.sf.net/sandbox/dkuhlman/>`__ and `his homepage
  25   <http://www.rexx.com/~dkuhlman/rstpythonlatex_intro.html>`__.
  26
  27
  28 Module information
  29 ''''''''''''''''''
  30
  31 Maybe make title "ctypes --- A foreign function library for Python"
  32 or use pep reader ?
  33
  34 For example ::
  35
  36   :Module: ctypes
  37   :Summary: A foreign function library for Python.
  38   :Module Type: standard
  39   :Author: Thomas Heller <theller@python.net>
  40   :Synopsis: A foreign function library for Python.
  41   :Version Added: 2.5
  42
  43
  44 Module and Summary are mandatory.
  45
  46 Problems
  47 ''''''''
  48
  49 * Tables
  50
  51   - For python documentation are typeset using ``\tableiii`` or
  52     ``\longtableiii``.
  53
  54     a. Only tables with two to five columns are supported.
  55     b. longtables should only be used for longer tables.
  56     c. Neither multicolumn nor multirow seam to be possible.
  57     d. All contents are left aligned.
  58     e. Which options for colfont are there: textrm, exception .
  59
  60   - An unpatched latex2html might be unable to handle ``longtable`` options.
  61     Maybe remove the ``[c]`` and put the longtable into a center environment.
  62
  63 * Document ``markup.py`` and ``missing.py``.
  64
  65 * Inline markup: email, note, pep, rfc, strong, ulink, url, warning
  66   might be already possible others require manual markup ?
  67   Or maybe seepep, ...
  68
  69 * see also environment.
  70
  71 * standard definition lists for or something else ?::
  72
  73     Arguments:
  74       file: a file name
  75
  76       encoding: a encoding
  77
  78 * if a definition has no classifier and starts with ``class`` use classdesc ?
  79
  80 * funcdesc arguments with default values should be marked as optional.
  81
  82
  83
  84 Link to Indexes
  85 '''''''''''''''
  86
  87 This is done by *informational units* (see `Documenting Python`_).
  88 ::
  89
  90   sizeof(type_or_object)
  91
  92       Returns the size in bytes of a ctypes type or instance memory
  93       buffer.  Does the same as the C sizeof() function.
  94
  95 should become ::
  96
  97   \begin{funcdesc}{sizeof}{type_or_object}
  98       Returns the size in bytes of a ctypes type or instance memory
  99           buffer.  Does the same as the C sizeof() function.
 100   \end{funcdesc}
 101
 102 this is done with definition lists with classifiers.
 103 Plain definition lists are only supported by transaltion to
 104 ``datadescni``, this might result in too much white space. ::
 105
 106   sizeof(type_or_object) : funcdesc
 107       Returns the size in bytes of a ctypes type or instance memory
 108       buffer.  Does the same as the C sizeof() function.
 109
 110 Note: the classifier must be preceeded by ``" : "`` (blank colon blank) and no
 111   blank line before the descriptional text.
 112
 113   And the definition, e.g. ``sizeof(...)`` is processed as text only,
 114   any markup like bold or literal is lost.
 115
 116 Environments (sorted by parameters)::
 117
 118   \begin{datadesc} {name}
 119   \begin{datadescni} {name}
 120   \begin{excdesc} {name}
 121   \begin{classdesc*} {name}
 122   \begin{csimplemacrodesc} {name}
 123
 124   \begin{ctypedesc} [tag]{name}
 125   \begin{memberdesc} [type name]{name}
 126   \begin{memberdescni} [type name]{name}
 127
 128   \begin{cvardesc} {type}{name}
 129   \begin{funcdesc} {name}{parameters}
 130   \begin{funcdescni} {name}{parameters}
 131   \begin{classdesc} {name}{constructor parameters}
 132   \begin{excclassdesc} {name}{constructor parameters}
 133
 134   \begin{methoddesc} [type name]{name}{parameters}
 135   \begin{methoddescni} [type name]{name}{parameters}
 136
 137   \begin{cmemberdesc} {container}{type}{name}
 138   \begin{cfuncdesc} {type}{name}{args}
 139
 140 The ``ni``-variants do not create index entries.
 141
 142 ``classdesc*`` describes a class without describing the constructor.
 143
 144 More beautiful would be to add some translation from rst-classifier
 145 to docpy markup. The desc can be skipped, "ni" should be written as
 146 "noindex" and the ``*`` variant should be detected as it has no
 147 parameter. e.g. ::
 148
 149   SerialAvail : function noindex
 150     this ...
 151
 152 This requires some thought interrest and feedback.
 153
 154 Change log
 155 ''''''''''
 156
 157 * mkpydoc.py:
 158
 159   - 2006-06-07: rename mkpydoc.py to rst2docpy.py and
 160                 remove informational units via topics.
 161   - 2006-06-03: add cmemberdesc.
 162   - 2006-06-02: support more informational units (cmemberdesc missing)
 163   - 2006-05-25: notice environment.
 164   - 2006-05-27:
 165
 166     - parameters in ``[]`` are marked optional.
 167     - definition lists with classifiers for information units.
 168   - 2006-05-13: Take moduleinfo from docinfo fields.
 169   - 2006-05-08: Change to generate pydoc tableii.
 170   - 2006-04-28:
 171
 172     - Patch for python 2.3.
 173     - Filenames from command line.
 174     - Guard definition of ``locallinewidth`` against redefinition.
 175     - latex needs definition of ``locallinewidth``.
 176
 177   - 2006-04-xx: from theller, ctypes repository.
 178
 179 .. _Docutils: http://docutils.sourceforge.net/
 180 .. _Documenting Python: <http://docs.python.org/dev/doc/doc.html>