[Doc-SIG] Creating a new type of document
David Goodger
goodger at python.org
Fri Apr 9 19:23:03 EDT 2004
Derek Wyatt wrote:
> First off... thanks for the tool. I love the markup language.
:-)
> I'm trying to use this to create a documentation centre within the
> company that i work for. I like the idea of PEPs (as i've stated on
> a previous message) but I don't like the PEP acronym
Understandable, if it doesn't fit your documents.
> What am i writing to accomplish this? I am getting a bit of a feel
> for how the system works and it looks like i'm not going to be
> writing a reader or parser since the file will be basic reST.
> However i think i need to write a transform, writer and a front-end.
> Is this correct?
I think you'll need:
* a Reader (subclasses of docutils.readers.pep classes should
suffice),
* transforms (subclasses/variations of docutils.transforms.peps
classes),
* a Writer (subclasses of docutils.writers.pep_html classes),
* a template file (variation of tools/pep-html-template),
* possibly a stylesheet (variation of tools/stylesheets/pep.css), and
* a front end (variation of tools/pep.py; don't use pep2html.py, which
contains a lot of non-Docutils legacy code).
It may be cleaner to generalize some of the PEP-specific classes for
easier subclassing; if so, we could add new generic "proposal" modules
that PEP modules could use.
> I could write an html munger that takes the output of the html.py
> front end and puts in the "DED nn" links and the links at the top,
> but it seems much cleaner to write something that can intercept the
> reST parsed output into XML and insert the stuff there.
Agreed. You may want to take a look at other projects that have done
the same thing:
* PEGs (Proposals for Enhancing Gzz):
http://himalia.it.jyu.fi/gzzdoc/pegboard/pegboard.gen.html
* GLEPs (Gentoo Linux Enhancement Proposals):
http://www.gentoo.org/proj/en/glep/
Both of these have adopted Python's PEP system and reStructuredText
for their own proposals. If anyone knows of other projects that have
done the same thing, please let me know. I haven't looked at any of
the actual code they use, so I can't say if it's done "correctly".
--
David Goodger http://python.net/~goodger
For hire: http://python.net/~goodger/cv
More information about the Doc-SIG
mailing list