Python Documentation Projects Developers Day 8th International Python Conference 27 January 2000

27 Jan 2000IPC8 Developers Day, Documentation-SIG 2 Open Projects Out-of-line documentation:  XML conversion of the standard documentation Embedded documentation:  David Ascher's docstring proposal  Fred's docstring + parse tree analysis tool

27 Jan 2000IPC8 Developers Day, Documentation-SIG 3 XML Conversion Project LaTeX files are loaded into DOM fragments  Markup interpretation is driven from a conversion specification written in XML DOM trees are modified from Python:  Augment existing markup  Performed in many simple passes  Paragraph identification at this stage ESIS can be converted to XML or SGML

27 Jan 2000IPC8 Developers Day, Documentation-SIG 4 XML Conversion Project Output is struturally similar to current markup  Some names change  Some data moves to attributes DTD has not been written:  Try DocBook (extended) or write our own?  If DocBook, conversion needs more work Not everything is perfect:  ~95% is handled automatically

27 Jan 2000IPC8 Developers Day, Documentation-SIG 5 What's Needed  Decision on DTD  Decision to use XML or SGML  *ML-savvy proofreaders to check conversion result

27 Jan 2000IPC8 Developers Day, Documentation-SIG 6 Selection of a DTD DocBook advantages:  Widely used, experienced designers  Existing stylesheets for print & Web DocBook disadvantages:  Verbose markup is hard to enter manually

27 Jan 2000IPC8 Developers Day, Documentation-SIG 7 Selection of a DTD Custom DTD advantages:  Can match the desired semantics precisely  Can use concepts and names familiar to Python programmers Custom DTD disadvantages:  We have to develop our own DTD when others have already made good ones  We're on our own for stylesheets

27 Jan 2000IPC8 Developers Day, Documentation-SIG 8 XML or SGML? XML advantages:  Easy to parse with Python  Good availability of tools XML disadvantages:  Markup is very verbose SGML advantages:  Markup can be somewhat more minimal, easier for authoring

27 Jan 2000IPC8 Developers Day, Documentation-SIG 9 Embedded Documentation Guido’s indicated an interest in “blessing” a format:  Extraction tools in standard library  Usable to derive sections of the Library Reference  Also useful for IDEs

27 Jan 2000IPC8 Developers Day, Documentation-SIG 10 Embedded Documentation  Markup/syntax proposal by David Ascher with contributions from SIG participants  We can get a lot of information directly from the source code  Tools based on Daniel Larsson's pythondoc, additional code by David Ascher and Fred Drake in progress (separately)

27 Jan 2000IPC8 Developers Day, Documentation-SIG 11 David’s Proposal Status  Syntax is “natural and Pythonic”  High-level structure is hashed out  Reference searching and recognition not quite done  Set of tags not yet solidified  Type syntax off-table to allow the Types- SIG time to work on it

27 Jan 2000IPC8 Developers Day, Documentation-SIG 12 David’s Implementation Prototype parser supports:  Indentation structure & tree building  Bold, italic, Python code, doctest tagging  List identification & tagging  Reference identification & tagging

27 Jan 2000IPC8 Developers Day, Documentation-SIG 13 David’s Implementation Missing features:  Signature parsing  Namespace lookup for references  doctest integration  Good error message with exact line numbers  Output formatting (will do HTML first)

27 Jan 2000IPC8 Developers Day, Documentation-SIG 14 Fred’s Implementation  No time to work on it  The code is a mess  Will be scrapped if we like David’s

27 Jan 2000IPC8 Developers Day, Documentation-SIG 15 Other Needs  Authors  Proofreaders  ???