[Grok-dev] grok reference - yet another test URL
uli at gnufix.de
Wed May 30 13:24:34 EDT 2007
yes, Jan-Wijbrand is right. I should have give you some more orientation
about the ongoing efforts on the reference. However, there is so much
for me to do and to learn simultanously at the moment, that you might
get the impression that nothing is happening. I am sorry for that.
Concerning the reference:
You can get an impression of my current state of reference-works
visiting the following URLS:
contains an HTML-version and
the accompanied PDF-version.
I know, it looks ugly and this is one reason for why I refused to put it
in public yet.
If you are interested in the dirty details:
The documentation above was generated running a nifty little script,
which produced the LaTeX source for further mkhowto-processing. Nothing
was edited by hand. The same script would - with some minimal
enhancements - happily produce also ReStructuredText documents.
The classes/attributes to examine/process were looked up in the
grok.interfaces roughly like this::
for name in IGrokBaseClasses:
The same for nearly all other interfaces from interfaces.py. To get the
elements to process this way, was an idea of Philipp (many thanks!). I
guess, such we can strike a balance between to little (document only the
things in __init__) and too much (document every element of the grok
The found interfaces/classes/functions then were processed looking for
attributes mainly using the zope.app.apidoc utilities. There is of
course much more information, one can get about every
class/attribute/interface: implemented interfaces, provided adapters and
many, many more. I simply had no time yet to use these apidoc features.
Also the types of all entities (functions/methods/classes/...) currently
appearing as 'class' can be handled differently according to their real
type. The same applies to the order of functions, methods and attributes
in every section. In that respects, a lot is possible.
The plain text documentation strings were extracted from (surprise,
surprise) the doc-strings in source code.
The processing script is already able to run in pedantic-mode in order
to put automatically missing-docstring-warnings into the reference.
My current problems with the reference:
- LaTeX versus ReST:
Although I personally like LaTeX very much, the docstrings usually
use restructured text to format special messages. For good reasons.
I therefore think of switching the whole reference base to ReST.
Some of the advantages:
+ code examples can be highlighted in a very readable manner
automatically (yes, this is also possible with LaTeX, but much
more difficult and error-prone).
+ restructured text markups in docstrings are much easier to learn
and most developers are used to it.
+ ReSTructuredText docs can easily be transformed to LaTeX
using docutils. The other way round is more complicated.
+ apidoc loves ReST. Doing the reference in ReST will result in
a formatting more similar to the admin-UI reference.
There are currently only little code examples in the generated ref.
Only a few from the doc-strings (which look really ugly). I would
like to append them with 'examples' from the tests. This is
not done at the moment, because there are much more 'examples' in
tests, than we really need.
My idea, similar to the convention-based naming of page templates
in grok, is: for every documented entity to look up the tests for
a module and package named like the currently processed item.
For example, if we want to process the entity "grok.Adapter", then
look for tests/adapter/adapter.py and take it as an example for
grok.Adapter. This could, however, be much nicer formatted, when
- Making a branch?
I did not open a branch in the repository because currently all I
have is an additional script to process the sources. Should I open
- Choosing the entities to document:
The currently used method (take all elements from the major
interfaces in grok.interfaces) is a good start from my point of
view. However, there might be things you want to see (or
_not_ to see), which are not covered in the generated reference
yet. Please specify, then I will try to include or exclude those
- Other People did reference work as well:
As stated in the list, others, namely Jan-Wijbrand, are already
working on the reference. I am not sure, whether an automatic
processing in that case makes sense or is at least desirable. I
would also be willing to do the reference work 'by hand' together
with others. Otherwise I would be happy to improve the automatic
processing, also together with volunteers if any. I am sure, we
anyway will get a good looking reference shortly :-)
Sorry again, for the long message!
More information about the Grok-dev