Sphinx Bootstrap Theme Customizer

Sphinx Bootstrap Theme brings to Sphinx documentation generator the variety of Bootswatch CSS themes. Though well organized, the process from customization to usable Sphinx theme is elaborate. This customizer automates that process.

As the Bootswatch themes were not specifically designed for styling code documentation, the CSS is also modified (see: sphinx.less and code_pygments.css files) to improve code layout and highlighting as required by sphinx. These modifications borrow from sphinx_rtd_theme.

How does it work?

The Bootswatch themes are designed in a dynamic form with a brand_color variable that governs most of color scheme. A bunch of other colors are generated from that one color alone. This customizer changes the @brand_color less variable of your preferred Bootswatch theme, and then builds a Sphinx theme.

Any variable defined in the variables.less file can be changed by using its name as the command-line argument followed by a replacement value.

Usage

To change the brand_color of for sandstone theme sandstone, cd into this projects directory, issue one command and a new theme will be generated.

$ build --theme sandstone --brand-primary '#AACCDD'

# other examples
$ build --theme darkly --body-bg blue \
    --panel-body-padding 15px \

If the --theme is not specified, the default value 'united'.

The created theme is stored in the theme directory. You can then copy that theme to the Sphinx directory and with these settings in conf.py it will be the theme that sphinx uses.

html_theme = 'theme'
html_theme_path = ['.']

See the Sphinx documentation on theming.

Requirements

The build tools used by Bootswatch themes require nodejs infrastructure. Assuming you use Linuxbrew or Homebrew, these commands will install the required packages as a user.

1. Clone repository:

   $ git clone https://github.com/has2k1/sphinx-bootstrap-theme-customizer
   

2. Install nodejs and npm:

   $ brew install nodejs
   $ brew install npm
   # fix npm path ...
   

These npm instructions may be useful.

3. Install less compile and css minifier:

   $ npm install -g less
   $ npm install -g clean-css
   $ npm install -g clean-css-cli
   

4. You can now do some customization, see usage information above.