Skip to content

Website Docs design

Jump to bottom Edit New page
vincentarelbundock edited this page Sep 23, 2012 · 3 revisions

Notes on website design and logos

Statsmodels docs are built using Sphinx and a variation on the Nature theme.

The look and feel is controlled by files in the statsmodels/docs/themes/statsmodels folder.

CSS

The main stylesheet used for setting colors, fonts, etc. is statsmodels/docs/themes/statsmodels/static/nature.css_t. This file is commented, but notice that:

  • div.headerwrap: controls top horizontal bar where the logo appear. This has a minimum size defined in the CSS file, but otherwise its height is controlled by the size of the logo we use (currently 85px high, used to be 115px). If logo is smaller than min-height, blank space is inserted.
  • div.related: controls the horizontal bar that comes right below the logo. This is what we use for navigation links (e.g. Bugs, Mailing list,
  • div.sphinxsidebar: Left-sidebar. Currently shows download links and google groups sign-up
  • pre: controls code block looks. Currently set the background to light gray, with some code-highlighting options

Static images

As far as I can tell, static images can be placed in statsmodels/docs/source/images/ or statsmodels/docs/themes/statsmodels/_static and both contents will be copied over to the build/html/_static directory upon build. You should link to images there.

Logo

In addition to static versions in the appropriate directory, we host the banner logo in vector format at statsmodels_hybi_banner.svg. This is the reference implementation, and most banners and icons should be derived form it. The background of this image should be set to the same color as the background-color of div.headerwrap, div.related, and header backgrounds in sphinxsidebar.

Expand/Collapse the Table of Contents

To expand and collapse the table of contents, we use mktree (MIT license). This requires inclusion of the following files in the static folder:

  • mktree.js
  • mktree.css
  • bullet.gif
  • plus.gif
  • minus.gif

The current solution is not really Sphinx-compliant, but it is very simple and works quite well:

  1. Build your docs as usual, using a toctree directive to generate a TOC
  2. use the tools/fold_toc.py helper script to insert links to mktree.js and mktree.css in the <head> of index.html
  3. use fold_toc.py to replace the toctree sphinx classes to mktree-compatible entries.
  4. Automate the process by executing fold_toc.py from docs/Makefile.
Add a custom footer
Add a custom sidebar
Clone this wiki locally