Sydebar: A browser sidebar generator for Python documentation

Description

Sydebar is a browser sidebar generator for Python documentation pages. It can generate Python documentation sidebars for all Python versions, with the documentation pages either local or on a remote web server.

Sydebar parses the documentation index of a specific version of Python, and generates a single, self-contained XHTML document with one panel per section for the following sections:

• Tutorial
• Language reference
• Library reference
• Python/C API
• Extending and embedding
• Global module index

Additionally, a search panel allows performing searches on the following sources:

• Various subsets of python.org, including the mailing list archives
• The Python Enhancement Proposals (PEPs)
• The comp.lang.python.* newsgroups
• The Python Package Index
• The Python issue tracker

Sydebar is released under the GNU General Public License version 2.

Quick start

Sample sidebars for all documentation versions available on python.org, generated with default parameters, can be found at this location.

To generate your own sidebar, proceed as follows:

• Download and unpack the source archive.
• Change the working directory to the root of the extracted directory tree and run the sidebar generator:

  bin/sydebar.py -o Sydebar-current.html
  

• Open the file Sydebar-current.html in your browser and override the default settings:

  file:///home/user/Sydebar-current.html?fontSize=13&fieldWidth=30&panel=Search
  

• Bookmark the page and configure the bookmark to open the page in the sidebar.

Installation

Sydebar requires Python 2.4 or later and probably runs on all platforms where Python runs. It has been tested on Linux and Windows. The latest version can be downloaded at this location. Installation is not really necessary, as the sydebar.py script in the bin folder can be run directly from an unpacked source archive. A system-wide installation can be performed anyway with the usual distutils command:

python setup.py install

Usage

Sydebar generates XHTML sidebars for specific versions of the Python documentation. The generated page must be bookmarked in the browser and set up to be displayed in the sidebar instead of the main browser pane.

Generating the sidebar document

This step takes a URL pointing to the index page of the documentation for a specific Python version and a few options as inputs, and outputs a self-contained XHTML file containing the sidebar data and code. It only has to be performed once per documentation URL.

Command line usage information for the program can be displayed with sydebar.py --help:

$ sydebar.py --help
Usage: sydebar.py [options]

Sydebar 1.0   A browser sidebar generator for Python documentation
Copyright (C) 2008 Remy Blank

Sydebar is a browser sidebar generator for Python documentation pages. It can
generate Python documentation sidebars for all Python versions. The
documentation pages can be either local or on a remote web server.

Options:
  --debug               Show a full traceback when exceptions are raised
                        during execution.
  -h, --help            Show this help message and exit.
  --version             Show the program version and exit.

  Input options:
    --image-clear=FILE  Read the 'clear' image from FILE. The default is
                        'clear.png'.
    --image-icon=FILE   Read the 'icon' image from FILE. The default is
                        'python.ico'.
    --image-minus=FILE  Read the 'minus' image from FILE. The default is
                        'minus.png'.
    --image-plus=FILE   Read the 'plus' image from FILE. The default is
                        'plus.png'.
    --image-search=FILE
                        Read the 'search' image from FILE. The default is
                        'search.png'.
    -t FILE, --template=FILE
                        Read the page template from FILE. The default is
                        'template.html'.
    -u URL, --url=URL   Generate the sidebar for the Python documentation
                        located at URL. The default is
                        'http://www.python.org/doc/2.4.4/'.

  Output options:
    -a, --all-versions  Generate sidebars for all documentation versions
                        available on python.org. The output file name must
                        contain a '%s' pattern that will be replaced by the
                        version string.
    -f N, --field-width=N
                        Set the width of text fields to N characters. The
                        default is 25.
    -n, --no-pack       Don't pack the resulting XHTML file (i.e. don't remove
                        non-significant white space). This will output nicely
                        indented and readable XHTML.
    -o FILE, --output=FILE
                        Write the output to FILE. If FILE is '-', the output
                        is written to standard output. The default is '-'.
    -p PANEL, --panel=PANEL
                        Show PANEL when loading the sidebar. PANEL can be one
                        of Tut, Ref, Lib, Api, Ext, Mod, Search. The default
                        is to show the module index if it is available, and
                        the tutorial otherwise.
    -s N, --font-size=N
                        Set the base font size to N pixels. The default is 11.

Input options

--image-clear=FILE, --image-icon=FILE, --image-minus=FILE, --image-plus=FILE, --image-search=FILE

Specify alternate image files for the clear button of the incremental search, the page icon, the minus and plus buttons for collapsing and expanding the trees, and the search tab and buttons, respectively. The images are embedded into the XHTML page as data: URIs.

-t FILE, --template=FILE

Specify an alternate page template for the sidebar. The template contains named string substitution references that are replaced by the relevant generated items using the string formatting operator %.

-u URL, --url=URL

Specify the base URL of the documentation for which the sidebar is to be generated. The URL can be either remote or local:

• Remote: The URL can point either to the entry page (index.html) or to the base folder. In the latter case, the terminating slash (/) is mandatory.

  Example: http://www.python.org/doc/2.4.4/

• Local: The URL has a file: schema and must point to the entry page, that is, including index.html.

  Example: file:///usr/share/doc/python-docs-2.4.4/html/index.html

The default is a remote URL to the documentation of the Python version running the program.

Output options

-a, --all-versions

Generate one sidebar for every documentation version available on python.org. The sidebars are written to separate files. The --output option becomes mandatory and it must contain a single %s pattern that will be replaced with the version string to construct the output file names.

-f N, --field-width=N

Specify the width of the search fields in characters.

-n, --no-pack

Don't pack the resulting XHTML file. The packing algorithm is very simple: it just removes any white space between > and < characters. Setting this option will make the program output nicely indented and readable XHTML.

-o FILE, --output=FILE

Write the generated XHTML to FILE. The default is to write to standard output, which can also be specified explicitly by passing '–' as FILE.

-p PANEL, --panel=PANEL

Specify the panel to be shown initially when the sidebar is loaded.

-s N, --font-size=N

Set the base font size to N pixels.

Examples

• Generate a sidebar for the documentation on python.org for the currently installed Python version:

  sydebar.py -o Sydebar-current.html
  

• Generate a sidebar for the same documentation as above, using a 15-pixel font, 30-character search fields, and display the search panel on load:

  sydebar.py -o Sydebar-current.html --text-size=15 --field-width=30 --panel=Search
  

• Generate a sidebar for locally-installed Python documentation:

  sydebar.py -o Sydebar-2.4.4.html -u file:///usr/share/doc/python-docs-2.4.4/html/index.html
  

• Generate a sidebar for every documentation version available on python.org, and write the output to Sydebar-1.4.html, Sydebar-1.5.html, ...:

  sydebar.py -a -o Sydebar-%s.html
  

Bookmarking the generated sidebar

The generated sidebar document can now be displayed in the main pane of a browser. To show it in the sidebar, it must be bookmarked specifically.

• In Firefox: Bookmark the page, open the properties of the bookmark and activate the option Load this bookmark in the sidebar.
• In Opera: Bookmark the page, open the properties of the bookmark and activate the option Show in panel.

Using the sidebar

The sidebar is structured as a deck of panels containing links to various sections of the documentation. Clicking a link opens the corresponding section in the main browser pane. The main features of the sidebar are the following:

• Tabbed panel selection: Select the desired documentation panel by clicking on the corresponding tab at the top of the sidebar. Clicking on the version number opens the root page of the documentation.
• Collapsible trees: The tutorial and reference panels show the outline of the corresponding documentation section as a tree. Click on a + to show the sub-sections, or on a – to hide them. The state of all trees is kept when switching panels, and is reset to "all closed" when reloading the sidebar.
• Incremental search in the module index: Enter a few characters in the text field at the top of the panel, and the list below is filtered to show only the entries that contain the given text.
• Keyboard navigation in the module index: After entering an incremental search term, navigate in the list with the cursor and page up and down keys. Press Esc to return to the incremental search field.
• Search panel: The search panel allows performing searches on various Python-related sources:
  • Website: Search various subsets of the python.org domain with Google.
  • PEPs: Enter a number to open the corresponding PEP directly, or enter search terms to search in all PEPs with Google.
  • Newsgroups: Search in all comp.lang.python.* newsgroups with Google Groups.
  • Package index: Search the Python Package Index using the search engine provided by PyPI.
  • Issue tracker: Enter a number to open the corresponding issue directly, or enter search terms to search in open or all issues using the issue tracker's search engine.

Load-time parameters

The appearance of the sidebar content is determined at generation time from the command line options. However, a few parameters can be changed at load-time through URL parameters:

fontSize=N

Set the base font size to N pixels. This parameter has the same effect as the --font-size command line option.

fieldWidth=N

Set the width of the search fields to N characters. This parameter has the same effect as the --field-width command line option.

panel=(Tut|Ref|Lib|Api|Ext|Mod|Search)

Specify the panel to be shown initially when the sidebar is loaded. This parameter has the same effect as the --panel command line option.

As an example, the following URL loads the sidebar with a font size of 15 pixels, a field width of 30 and initially shows the search panel:

file:///home/user/Sydebar-current.html?fontSize=15&fieldWidth=30&panel=Search

Known issues

Sydebar has been tested with Python 2.4.4 on Linux and Windows. Moreover, the generated pages have been tested in Firefox 2.0.0.14 and Opera 9.27. This section documents the issues that have appeared during testing, and for which I haven't found a solution yet.

• The layout is not completely static. I would really like to fix this, so if you know how to do the following in pure CSS, please let me know:
  • Center an image vertically relative to a text line (in this case, the plus and minus images in the collapsible trees)
  • Make a square search button with the same height as the associated search field
  Currently, after loading the page, a few measurements are taken on displayed (but invisible) objects, and a few CSS attributes are adjusted to make the layout right.
• The page icon does not appear on the bookmark for any of the browsers I have tested, even though it appears on the address bar. Firefox shows no icon at all, and Opera shows a generic icon.
• There is a small display glitch in Opera on the first cursor down from the incremental search field. The focus correctly goes to the first list element, but the pane scrolls down as well. It seems that the "cursor down" event gets passed to the window despite calling event.preventDefault(). The same happens with page down.
• The language reference panels for Python versions before 1.5.1p1 are incomplete. For 1.4, the panel is even completely wrong. I will not fix this issue, as I assume that these versions are not in widespread use anymore, and the data extractors are convoluted enough without taking these cases into account.

Feedback

If you are using Sydebar, please let me know! I'm especially interested in bug reports, improvement ideas, and compatibility fixes.

Links

• python-sidebar: This archived project by Daniel Lundin at Edgewall Software was the initial inspiration for writing Sydebar. Actually, the idea was to revive python-sidebar and bring it up-to-date (and adapting it to the changes in the generation of the Python documentation). In the end, I restarted from scratch anyway, as some of the ideas I had (like having the whole sidebar in one HTML file instead of several) would have been cumbersome to implement in python-sidebar. Moreover, I wanted to explore various techniques like web scraping, CSS formatting of an XHTML page, and DHTML with JavaScript. Still, the concept and visual layout come from there (as well as the search icon).
• Mark Hammond's sidebar: This sidebar is written in XUL and is oriented more towards flexible search functions.
• Python: The programming language.

Copyright (C) 2008 Remy Blank