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