Cadnano2.5 documentation is built with sphinx and hosted at

Building the docs


pip3 install sphinx sphinx_rtd_theme==0.2.5b2 recommonmark sphinx-autobuild
cd cadnano/docs
make clean
make api
make html
make livehtml

Getting started

Try setting up your own separate test sphinx project using sphinx-quickstart. Once you understand how sphinx works, read through the cadnano/docs Makefile and to understand our configuration.

Install dependencies

From the terminal, use pip to install sphinx and cadnano docs dependencies.

pip3 install sphinx sphinx_rtd_theme==0.2.5b2 recommonmark sphinx-autobuild


First, make sure you are in the docs directory. Clear out the old documentation, if any.

cd cadnano/docs
make clean

Build the API. This generates sphinx .rst sources in docs/api using sphinx-autodoc.

make api

Build the html. This converts the .rst and .md sources into HTML files. If successful, HTML pages should be placed in _build/html. You can open the index.html to inspect your edits.

make html

If you want to do everything together in a single command:

make clean; make api; make html


It can get tedious to rebuild the docs during heavy editing sessions. Instead, you can use sphinx-autobuild to rebuild the documentation whenever a change is detected. Autobuild conveniently spawns a local server (at unless you specify otherwise with -p) that will refresh as needed.

make livehtml

reStructuredText vs Markdown

Like docutils, Sphinx uses reStructuredText, whose filenames have an .rst extension. ReStructuredText is tailored for technical documentation, and predates Markdown by about 2 years.

For the sake of consistency and leveraging core sphinx features, we initially just learned the basics of rST and used it for most doc sources, including the API. However, it is possible to create documentation in markdown format using recommonmark. This source files for this page (cadnano/docs/ New top-level documentation files that do not require rsT features should be created in markdown with the .md extension.

Known Issues

toctree Warnings

When building the docs, you may see warnings like:

WARNING: toctree contains reference to nonexisting document 'api/cadnano.controllers.documentcontroller'
WARNING: toctree contains reference to nonexisting document 'api/cadnano.gui.mainwindow.ui_mainwindow'
WARNING: toctree contains reference to nonexisting document 'api/cadnano.views.cnmainwindow'
WARNING: toctree contains reference to nonexisting document 'api/cadnano.views.outlinerview.outlinertreewidget'

These modules import the PyQt5 classes in a way that doesn’t play nicely with sphinx, so they are specifically excluded in docs/ Consequently, the documentation for these modules will be missing until someone tracks down the root cause of this issue and figures out a workaround. Possible starting point:


You may see segfaults when trying to run make html or make livehtml that look like this:

reading sources... [ 70%] api/cadnano.views.pathview.strand.stranditem
reading sources... [ 71%] api/cadnano.views.pathview.strand.xoveritem
reading sources... [ 71%] api/
reading sources... [ 72%] api/
reading sources... [ 72%] api/
make: *** [html] Segmentation fault: 11

If you encounter this, you may need to exclude the offending source from the build. Add the last source read before the segfault to the exclude_patterns list in Ensure that you include the trailing .rst in the string.


We welcome docs-related pull requests, especially those that improve the docstring coverage of the API. Contributors will be credited on the AUTHORS page. If you are interested to help but not sure where to begin, please contact us!