[Docutils-develop] ELISP parser front-end

[Martin B. <bl...@fu...>]

Hi

I have a few emacs LISP packages that I shared with the world and I
wish to put more of them online.  In order to generete an HTML web
page for each of these, right now, I simply write the documentation in
reStructuredText at the top of the file and I LISP-comment it.  Then I
have a simple Python script that extracts this block and converts it
into HTML using docutils.  This makes a page that looks like this:

http://furius.ca/pubcode/pub/conf/common/elisp/blais/dubious-paragraphs.el.html

However, the resulting LISP code does not comply with the conventions
of emacs LISP.  M-x checkdoc fails miserably.  Emacs has its own
conventions for formatting the LISP code and the included
documentation at the top, and everybody complies, due to checkdoc, and
this provides a certain level of consistency.

So I would like to convert my LISP code to be consistent with the
emacs conventions, and yet to find a way for docutils to be able to
read it into a doctree to generate its documentation.

I looked at the format, and was going to start writing a parser for
it, but I realize how that it would be much easier to just write a
script to transform the emacs LISP conventions into an rst file and
then run the standalone reader on it.  I thought I might be able to do
that by providing a custom reader.  So I looked at the pep reader for
an example, and what it does it really just via some transforms, i.e.
it takes the first paragraph and interprets it as RFC822, and the rest
of the file is just valid rest anyway.

In the case of emacs lisp, I would really have to modify the contents
of the input *before* running it throught the parser, to remove the
comments, identify the section titles and add the underlines, and to
convert :$ into :: for literal blocks.  That's pretty much it.

Does it make sense to implement this as a custom reader?



P.S. this project could be a cool way to generate HTML documentation
for all of the emacs LISP library :-)