Index of /sandbox/docpy-writer (original) (raw)

Docutils for python documentation

Contact:

grubert@users.sourceforge.net

Revision:

8227

Date:

2018-07-21

Copyright:

This document has been placed in the public domain.

This tried, at a time when texinfo was used, to explore the posibilities to use docutils as format for python library documentation as specified inDocumenting Python .

This version is based on a script from Greg Ward, hacked by Thomas Heller.

There is also

Module information

Maybe make title "ctypes --- A foreign function library for Python" or use pep reader ?

For example

:Module: ctypes :Summary: A foreign function library for Python. :Module Type: standard :Author: Thomas Heller theller@python.net :Synopsis: A foreign function library for Python. :Version Added: 2.5

Module and Summary are mandatory.

Problems

This is done by informational units (see Documenting Python).

sizeof(type_or_object)

Returns the size in bytes of a ctypes type or instance memory
buffer.  Does the same as the C sizeof() function.

should become

\begin{funcdesc}{sizeof}{type_or_object} Returns the size in bytes of a ctypes type or instance memory buffer. Does the same as the C sizeof() function. \end{funcdesc}

this is done with definition lists with classifiers. Plain definition lists are only supported by transaltion todatadescni, this might result in too much white space.

sizeof(type_or_object) : funcdesc Returns the size in bytes of a ctypes type or instance memory buffer. Does the same as the C sizeof() function.

Note: the classifier must be preceeded by " : " (blank colon blank) and no

blank line before the descriptional text.

And the definition, e.g. sizeof(...) is processed as text only, any markup like bold or literal is lost.

Environments (sorted by parameters):

\begin{datadesc} {name} \begin{datadescni} {name} \begin{excdesc} {name} \begin{classdesc*} {name} \begin{csimplemacrodesc} {name}

\begin{ctypedesc} [tag]{name} \begin{memberdesc} [type name]{name} \begin{memberdescni} [type name]{name}

\begin{cvardesc} {type}{name} \begin{funcdesc} {name}{parameters} \begin{funcdescni} {name}{parameters} \begin{classdesc} {name}{constructor parameters} \begin{excclassdesc} {name}{constructor parameters}

\begin{methoddesc} [type name]{name}{parameters} \begin{methoddescni} [type name]{name}{parameters}

\begin{cmemberdesc} {container}{type}{name} \begin{cfuncdesc} {type}{name}{args}

The ni-variants do not create index entries.

classdesc* describes a class without describing the constructor.

More beautiful would be to add some translation from rst-classifier to docpy markup. The desc can be skipped, "ni" should be written as "noindex" and the * variant should be detected as it has no parameter. e.g.

SerialAvail : function noindex this ...

This requires some thought interrest and feedback.

Change log