[Grok-dev] grok reference - yet another test URL

[Uli Fouquet]

Hello grokkers,

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:

	https://gf1.gnufix.de/~uli/grok/reference/html/

contains an HTML-version and

	https://gf1.gnufix.de/~uli/grok/reference/reference.pdf

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:
       handle_section(name)

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
package) information.

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.

  - Code-Examples:

     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
     using restructuredText.

  - 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
     one?

  - 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
     elements.

  - 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!

Kind regards

-- 
Uli