Sydebar: A browser sidebar generator for Python documentation
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:
- 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 Python Package Index
- The Python issue tracker
Sydebar is released under the GNU General Public License version 2.
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:
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
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
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.
--debug Show a full traceback when exceptions are raised
-h, --help Show this help message and exit.
--version Show the program version and exit.
--image-clear=FILE Read the 'clear' image from FILE. The default is
--image-icon=FILE Read the 'icon' image from FILE. The default is
--image-minus=FILE Read the 'minus' image from FILE. The default is
--image-plus=FILE Read the 'plus' image from FILE. The default is
Read the 'search' image from FILE. The default is
-t FILE, --template=FILE
Read the page template from FILE. The default is
-u URL, --url=URL Generate the sidebar for the Python documentation
located at URL. The default is
-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
-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.
- --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
- -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:
The default is a remote URL to the documentation of the Python version running the program.
- -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
- -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.
- Generate a sidebar for the documentation on
python.org for the currently installed
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.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 panel: The search panel allows performing searches on various Python-related
- 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.
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:
- Set the base font size to N pixels. This parameter has the same effect as the
--font-size command line option.
- Set the width of the search fields to N characters. This parameter has the same effect
as the --field-width command line option.
- 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:
Sydebar has been tested with Python 2.4.4 on Linux and Windows. Moreover, the generated pages have
been tested in Firefox 22.214.171.124 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:
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.
- 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
- 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
- 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.
If you are using Sydebar, please let me know!
I'm especially interested in bug reports, improvement ideas, and compatibility fixes.
- 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
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