python documentation projects developers day 8th international python conference 27 january 2000

Python Documentation Projects

Developers Day

8th International Python Conference

27 January 2000

27 Jan 2000 IPC8 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


3

XML Conversion Project

LaTeX files are loaded into DOM fragmentsMarkup 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


4

XML Conversion Project

Output is struturally similar to current markupSome 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


5

What's Needed

Decision on DTDDecision to use XML or SGML*ML-savvy proofreaders to check

conversion result


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


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


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


9

Embedded Documentation

Guido’s indicated an interest in “blessing” a format:Extraction tools in standard libraryUsable to derive sections of the Library

ReferenceAlso useful for IDEs


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)


11

David’s Proposal Status

Syntax is “natural and Pythonic”High-level structure is hashed outReference searching and recognition not

quite doneSet of tags not yet solidifiedType syntax off-table to allow the Types-

SIG time to work on it


12

David’s Implementation

Prototype parser supports:Indentation structure & tree buildingBold, italic, Python code, doctest taggingList identification & taggingReference identification & tagging


13

David’s Implementation

Missing features:Signature parsingNamespace lookup for referencesdoctest integrationGood error message with exact line numbersOutput formatting (will do HTML first)


14

Fred’s Implementation

No time to work on itThe code is a messWill be scrapped if we like David’s


15

Other Needs

AuthorsProofreaders???

python documentation projects developers day 8th international python conference 27 january 2000

Documents