Live Documentation in the Notebook

Processes Sage documentation into notebook worksheet format with evaluable examples.

This takes in any HTML document, i.e., Sage documentation, and returns it in the editable format (like the notebook edit window). It also returns a string representing the CSS link for the document. The SGML parser is setup to return only the body of the HTML documentation page and to re-format Sage examples and type-setting.

Note: This extension of sgmllib.SGMLParser was partly inspired by Mark Pilgrim’s ‘Dive Into Python’ examples.

Author:

• Dorian Raymer (2006): first version
• William Stein (2007-06-10): rewrite to work with twisted Sage notebook
• Mike Hansen (2008-09-27): Rewrite to work with Sphinx HTML documentation

class sagenb.notebook.docHTMLProcessor.SphinxHTMLProcessor(verbose=0)

Bases: sgmllib.SGMLParser

end_div()

end_form()

end_pre()

end_span()

get_cellcount()

Return the current cell count and increment it by one.

OUTPUT:

• an int

EXAMPLES:

sage: from sagenb.notebook.docHTMLProcessor import SphinxHTMLProcessor
sage: d = SphinxHTMLProcessor()
sage: d.get_cellcount()
0
sage: d.get_cellcount()
1

hand_off_temp_pieces(piece_type)

To separate the documentation’s content from the Sage examples, everything is split into one of two cell types. This method puts the current self.temp_pieces into self.all_pieces.

INPUT:

• piece_type - a string; indicates the type of and how to process the current self.temp_pieces

handle_charref(ref)

handle_comment(data)

handle_data(data)

handle_decl(text)

handle_entityref(ref)

handle_pi(text)

process_cell_input_output(cell_piece)

Process and return a cell_piece.

All divs with CSS class=”highlight” contain code examples. They include

• Models of how the function works. These begin with, e.g., ‘INPUT:’ and are re-styled as divs with class=”usage_model”.
• Actual Sage input and output. These begin with ‘sage:’. The input and output are separated according to the Notebook edit format.

INPUT:

• cell_piece - a string; a cell piece

OUTPUT:

• a string; the processed cell piece

process_doc_html(doc_in)

Returns processed HTML input as HTML output. This is the only method that needs to be called externally.

INPUT:

• doc_in - a string containing properly formed HTML

OUTPUT:

• a string; the processed HTML

reset()

Initialize necessary variables. Called by SGMLParser.__init__().

EXAMPLES:

sage: from sagenb.notebook.docHTMLProcessor import SphinxHTMLProcessor
sage: d = SphinxHTMLProcessor()
sage: d.bodyQ
False
sage: d.in_highlight_div
False
sage: d.temp_pieces
[]
sage: d.all_pieces
''
sage: d.cellcount
0

start_body(attrs)

Set self.bodyQ to True upon finding the opening body tag.

INPUT:

• attrs - a string:string dictionary containing the element’s attributes

EXAMPLES:

sage: from sagenb.notebook.docHTMLProcessor import SphinxHTMLProcessor
sage: d = SphinxHTMLProcessor()
sage: d.bodyQ
False
sage: d.start_body(None)
sage: d.bodyQ
True

start_div(attrs)

start_form(attrs)

start_pre(attrs)

start_span(attrs)

unknown_endtag(tag)

unknown_starttag(tag, attrs)