Caktus Sphinx Theme
Custom Sphinx theme for projects written and maintained by Caktus Consulting Group.
Quick Links
Development of this project is sponsored by Caktus Consulting Group, LLC. You can see more of our projects on our Github page.
Caktus Sphinx Theme¶
This is a custom Sphinx theme used for documenting projects written and maintained by Caktus Consulting Group.
Installing¶
There are no current releases of this theme but you can install directly from Github:
pip install git+git://github.com/caktus/caktus-sphinx-theme.git#egg=caktus-sphinx-theme
Once installed you should change your Sphinx conf.py to include:
import caktus_theme
html_theme = 'caktus'
html_theme_path = [caktus_theme.get_theme_dir()]
html_sidebars = caktus_theme.default_sidebars()
To use the Pygments style from the theme you should ensure that pygments_style is
not set.
For additional detail on configuring the theme, please read the full usage documentation.
Documentation¶
Additional documentation on using caktus-sphinx-theme is available on Read The Docs. The documentation also uses the theme so you can see an example of the style.
License¶
caktus-sphinx-theme is released under the BSD License. The theme itself contains a number of references to Caktus Consulting Group including logos but you are free to adapt this theme for your own uses. See the LICENSE file for more details.
This theme makes use of the Semantic Grid System which is available under the Apache 2.0 license.
Contents¶
Theme Examples¶
This page is to serve as example of how the theme handles various pieces of documentation.
Python Code¶
import random
if random.random() < 0.5:
print 'You win!'
else:
print 'You lose.'
HTML Code¶
<form method='post' action=''>
<input type='text' name='username'>
<input type='password' name='passowrd'>
<button type='submit'>Submit</button>
</form>
Block Quotes¶
This is a quote
Quotation, n: The act of repeating erroneously the words of another.
—Ambrose Bierce
Notes¶
Note
This is a note
Warning
This is a warning
Changed in version 0.1: This changed in some version
Deprecated since version 0.1: This was deprecated in some version
See also
You should see some other section for more info
Using this Theme¶
Here you will find comprehensive details on installing and configuring your Sphinx documentation to use this theme. You will also find optional configuration flags.
Installation¶
There are no current releases of this theme but you can install directly from Github:
pip install git+git://github.com/caktus/caktus-sphinx-theme.git#egg=caktus-sphinx-theme
Basic Sphinx Configuration¶
To configure Sphinx to use the theme you should make the following changes to your
Sphinx configuration conf.py.
import caktus_theme
html_theme = 'caktus'
html_theme_path = [caktus_theme.get_theme_dir()]
html_sidebars = caktus_theme.default_sidebars()
In addition the pygments_style configuration should be commented out or removed
# pygments_style = 'sphinx'
if you wish to use the default Pygments style for the theme (friendly).
Additional Theme Configuration¶
Beyond the above configuration to use the theme for your documentation, there are
additional flags which can be set using the html_theme_options dictionary. An
example is given below.
html_theme_options = {
'tagline': caktus_theme.__doc__,
'links': {
'github': 'https://github.com/caktus/caktus-sphinx-theme',
},
'forkme': 'right',
}
These theme options assume that you are using the default sidebars given by
caktus_theme.default_sidebars as previously configured.
tagline¶
The tagline key in the html_theme_options defines the text which is present
on the top the sidebar just below the project name. This should be used to give a
brief description of the project and its purpose. It is recommened that this
match the description given in the project’s setup.py if there is one.
links¶
The links option is a dictionary of links to be displayed on the index page
sidebar under the Quick Links heading. The set of recongnized keys are given below
- pypi: Link to the project’s page on the Python Package Index
- github: Link to the project source on Github. This will also include a link to the issue tracker
- demo: Link to a publicly accessible live demo
- mail: Link to the project’s mailing list
If the links key is not given in html_theme_options then the Quick Links section
will not display. If one of the above link types is not present then that link
will not be shown in the listing.
forkme¶
forkme configures if/how the “Fork me on Github”
banner is included on the documentation. By default the banner will display on the right-hand side
if a Github link is included in the above links configuration. You may choose to have
this display on the left side by setting this to left or disabling the banner by
setting this option to an empty string or None. Regardless of the positioning the
banner will only display on the index of the documentation.
Contributing Guide¶
The guide covers the development of the theme itself. This includes the tools used and the workflow for contributing changes.
Development Tools¶
This is a custom theme Sphinx which makes it a large dependancy. Instead of using the CSS templates this theme makes use of LESS to create dynamic style sheets. For quickly building the theme CSS and documentation this project uses tox.
Installing the LESS Compiler¶
If you plan on making changes to the theme CSS you should have the LESS compiler installed. This should be installed globally from NPM:
npm install less -g
If you don’t have NPM installed you can get it from the following PPA:
sudo apt-get install python-software-properties
sudo add-apt-repository ppa:chris-lea/node.js
sudo apt-get update
sudo apt-get install nodejs npm
Installing Tox¶
Tox is easiest to install from PyPi:
pip install tox
The configuration is defined in the tox.ini file. You can use tox to build
the LESS to CSS with:
tox -e less
Or build the latest documentation for the theme with:
tox -e doc
Or build the CSS then the docs with:
tox