Verified Commit 387f3d71 authored by Adel Kara Slimane's avatar Adel Kara Slimane
Browse files

Add Sphinx documentation and related config files

parent 16a07b31
# Makefile for Sphinx documentation
# You can set these variables from the command line.
SPHINXBUILD = sphinx-build
BUILDDIR = build
# Set Python search path so that autodoc as well as jupyter-sphinx will find
# the correct tkwant version to be documented.
codebuilddir = $(shell python3 -c 'import sys, distutils.util; print("../build/lib.{0}-{1}.{2}".format(distutils.util.get_platform(), *sys.version_info[:2]))')
export PYTHONPATH := $(abspath $(codebuilddir)):$(PYTHONPATH)
# User-friendly check for sphinx-build
ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1)
$(error The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed, then set the SPHINXBUILD environment variable to point to the full path of the '$(SPHINXBUILD)' executable. Alternatively you can add the directory with the executable to your PATH. If you don\'t have Sphinx installed, grab it from
# Internal variables.
PAPEROPT_a4 = -D latex_paper_size=a4
PAPEROPT_letter = -D latex_paper_size=letter
# the i18n builder cannot share the environment and doctrees with the others
.PHONY: help
@echo "Please use \`make <target>' where <target> is one of"
@echo " html to make standalone HTML files"
@echo " dirhtml to make HTML files named index.html in directories"
@echo " singlehtml to make a single large HTML file"
@echo " pickle to make pickle files"
@echo " json to make JSON files"
@echo " htmlhelp to make HTML files and a HTML help project"
@echo " qthelp to make HTML files and a qthelp project"
@echo " applehelp to make an Apple Help Book"
@echo " devhelp to make HTML files and a Devhelp project"
@echo " epub to make an epub"
@echo " epub3 to make an epub3"
@echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
@echo " latexpdf to make LaTeX files and run them through pdflatex"
@echo " latexpdfja to make LaTeX files and run them through platex/dvipdfmx"
@echo " text to make text files"
@echo " man to make manual pages"
@echo " texinfo to make Texinfo files"
@echo " info to make Texinfo files and run them through makeinfo"
@echo " gettext to make PO message catalogs"
@echo " changes to make an overview of all changed/added/deprecated items"
@echo " xml to make Docutils-native XML files"
@echo " pseudoxml to make pseudoxml-XML files for display purposes"
@echo " linkcheck to check all external links for integrity"
@echo " doctest to run all doctests embedded in the documentation (if enabled)"
@echo " coverage to run coverage check of the documentation (if enabled)"
@echo " dummy to check syntax errors of document sources"
ROOT_DIR:=$(shell dirname $(realpath $(firstword $(MAKEFILE_LIST))))
.PHONY: clean
rm -rf $(BUILDDIR)/*
rm -rf source/reference/generated
.PHONY: html
@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
.PHONY: dirhtml
@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
.PHONY: singlehtml
$(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
@echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
.PHONY: pickle
@echo "Build finished; now you can process the pickle files."
.PHONY: json
@echo "Build finished; now you can process the JSON files."
.PHONY: htmlhelp
$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
@echo "Build finished; now you can run HTML Help Workshop with the" \
".hhp project file in $(BUILDDIR)/htmlhelp."
.PHONY: qthelp
@echo "Build finished; now you can run "qcollectiongenerator" with the" \
".qhcp project file in $(BUILDDIR)/qthelp, like this:"
@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/tkwant.qhcp"
@echo "To view the help file:"
@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/tkwant.qhc"
.PHONY: applehelp
$(SPHINXBUILD) -b applehelp $(ALLSPHINXOPTS) $(BUILDDIR)/applehelp
@echo "Build finished. The help book is in $(BUILDDIR)/applehelp."
@echo "N.B. You won't be able to view it unless you put it in" \
"~/Library/Documentation/Help or install it in your application" \
.PHONY: devhelp
@echo "Build finished."
@echo "To view the help file:"
@echo "# mkdir -p $$HOME/.local/share/devhelp/tkwant"
@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/tkwant"
@echo "# devhelp"
.PHONY: epub
@echo "Build finished. The epub file is in $(BUILDDIR)/epub."
.PHONY: epub3
@echo "Build finished. The epub3 file is in $(BUILDDIR)/epub3."
.PHONY: latex
@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
@echo "Run \`make' in that directory to run these through (pdf)latex" \
"(use \`make latexpdf' here to do that automatically)."
.PHONY: latexpdf
@echo "Running LaTeX files through pdflatex..."
$(MAKE) -C $(BUILDDIR)/latex all-pdf
@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
.PHONY: latexpdfja
@echo "Running LaTeX files through platex and dvipdfmx..."
$(MAKE) -C $(BUILDDIR)/latex all-pdf-ja
@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
.PHONY: text
@echo "Build finished. The text files are in $(BUILDDIR)/text."
.PHONY: man
@echo "Build finished. The manual pages are in $(BUILDDIR)/man."
.PHONY: texinfo
@echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo."
@echo "Run \`make' in that directory to run these through makeinfo" \
"(use \`make info' here to do that automatically)."
.PHONY: info
@echo "Running Texinfo files through makeinfo..."
make -C $(BUILDDIR)/texinfo info
@echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo."
.PHONY: gettext
$(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale
@echo "Build finished. The message catalogs are in $(BUILDDIR)/locale."
.PHONY: changes
@echo "The overview file is in $(BUILDDIR)/changes."
.PHONY: linkcheck
$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
@echo "Link check complete; look for any errors in the above output " \
"or in $(BUILDDIR)/linkcheck/output.txt."
.PHONY: doctest
@echo "Testing of doctests in the sources finished, look at the " \
"results in $(BUILDDIR)/doctest/output.txt."
.PHONY: coverage
$(SPHINXBUILD) -b coverage $(ALLSPHINXOPTS) $(BUILDDIR)/coverage
@echo "Testing of coverage in the sources finished, look at the " \
"results in $(BUILDDIR)/coverage/python.txt."
.PHONY: xml
@echo "Build finished. The XML files are in $(BUILDDIR)/xml."
.PHONY: pseudoxml
$(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml
@echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml."
.PHONY: dummy
@echo "Build finished. Dummy builder generates no files."
/* This theme is based on pydoctheme by Georg Brandl. */
@import url("default.css");
body {
background-color: white;
margin-left: 1em;
margin-right: 1em;
/* Disable typewriter font in headings. */
h1 tt, h2 tt, h3 tt, h4 tt, h5 tt, h6 tt {
font-family: "Bitstream Vera Sans", Verdana, sans-serif;
font-size: 100%;
div.body p, div.body dd, div.body li {
-webkit-hyphens: auto;
-moz-hyphens: auto;
-ms-hyphens: auto;
-o-hyphens: auto;
hyphens: auto;
div.related {
margin-bottom: 1.2em;
padding: 0.5em 0;
border-top: 1px solid #ccc;
margin-top: 0.5em;
dt:target, .highlighted {
background-color: #fbf1aa;
div.related:first-child {
border-top: 0;
border-bottom: 1px solid #ccc;
div.sphinxsidebar {
background-color: #eeeeee;
border-radius: 5px;
line-height: 130%;
font-size: smaller;
overflow: hidden;
div.sphinxsidebar h3, div.sphinxsidebar h4 {
margin-top: 1.5em;
div.sphinxsidebarwrapper > h3:first-child {
margin-top: 0.2em;
div.sphinxsidebarwrapper > ul > li > ul > li {
margin-bottom: 0.4em;
div.sphinxsidebar input {
font-family: 'Bitstream Vera Serif', Georgia, serif
border: 1px solid #999999;
font-size: smaller;
border-radius: 3px;
div.sphinxsidebar input[type=text] {
max-width: 220px;
div.body {
padding: 0 0 0 1.2em;
div.body p {
line-height: 140%;
div.body h1, div.body h2, div.body h3, div.body h4, div.body h5, div.body h6 {
margin: 0;
border: 0;
padding: 0.3em 0;
div.body hr {
border: 0;
background-color: #ccc;
height: 1px;
div.body pre {
border-radius: 3px;
border: 1px solid #ac9;
div.body div.admonition, div.body div.impl-detail {
border-radius: 3px;
div.body div.impl-detail > p {
margin: 0;
div.body div.seealso {
border: 1px solid #dddd66;
tt, pre {
font-family: monospace, sans-serif;
font-size: 96.5%;
-webkit-hyphens: none;
-moz-hyphens: none;
-ms-hyphens: none;
-o-hyphens: none;
hyphens: none;
div.body tt {
border-radius: 3px;
div.body tt.descname {
font-size: 120%;
div.body tt.xref, div.body a tt {
font-weight: normal;
p.deprecated {
border-radius: 3px;
table.docutils {
border: 1px solid #ddd;
min-width: 20%;
border-radius: 3px;
margin-top: 10px;
margin-bottom: 10px;
table.docutils td, table.docutils th {
border: 1px solid #ddd !important;
border-radius: 3px;
table p, table li {
text-align: left !important;
table.docutils th {
background-color: #eee;
padding: 0.3em 0.5em;
table.docutils td {
background-color: white;
padding: 0.3em 0.5em;
table.footnote, table.footnote td {
border: 0 !important;
div.footer {
line-height: 150%;
margin-top: -2em;
text-align: right;
width: auto;
margin-right: 10px;
/* have arguments of functions or classes also a monospace font */
table.longtable.docutils > tbody > tr > td:first-child,
dl.function > dt,
dl.class > dt,
dl.method > dt
font-family: "Bitstream Vera Sans Mono", monospace, serif;
font-size: 96.5%;
/* rescale font for <tt> so that it is again 96.5% with respect to body */
table.longtable.docutils > tbody > tr > td:first-child tt,
dl.function > dt tt,
dl.class > dt tt,
dl.method > dt tt
font-family: "Bitstream Vera Sans Mono", monospace, serif;
font-size: 100%;
td.field-body strong
font-family: "Bitstream Vera Sans Mono", monospace, serif;
font-size: 96.5%;
# This theme is based on pydoctheme by Georg Brandl
inherit = default
stylesheet = kwantdoctheme.css
pygments_style = sphinx
bodyfont = "Bitstream Vera Serif", Georgia, serif
headfont = "Bitstream Vera Sans", Verdana, sans-serif
footerbgcolor = white
footertextcolor = #555555
relbarbgcolor = white
relbartextcolor = #666666
relbarlinkcolor = #444444
sidebarbgcolor = white
sidebartextcolor = #444444
sidebarlinkcolor = #444444
sidebarwidth = 300
bgcolor = white
textcolor = black
linkcolor = #045e94
visitedlinkcolor = #045e94
headtextcolor = black
headbgcolor = white
headlinkcolor = #aaaaaa
@import "kwantdoctheme.css";
/* spacing around blockquoted fields in parameters/attributes/returns */
/* Essential. Otherwise there is way too much space around*/
td.field-body > blockquote {
margin-top: 0.1em;
margin-bottom: 0.5em;
.field-list th {
/* color: rgb(0,50,150); */
/* background-color: #EEE8AA; */
white-space: nowrap; /* Essential. Otherwise the colons can break
into a new line */
table.field-list {
border-collapse: separate; /* Essential. Otherwise Parameters and Returns
are sharing one solid colored field. That looks
weird. */
border-spacing: 10px;
border-style: hidden;
div.specialnote-title {
font-size: 105%;
font-weight: bold;
font-color: #3B4D3C;
background-color: #DCE4DC;
padding: 1em;
padding-top: 0.4em;
padding-bottom: 0.4em;
margin-top: 10px;
margin-bottom: 10px;
border-width: 1px;
border-color: #546C55;
border-style: solid;
div.specialnote-body {
background-color: #DCE4DC;
padding: 1em;
padding-top: 0.1em;
padding-bottom: 0.4em;
margin-top: -10px;
margin-bottom: 10px;
border-width: 1px;
border-top-width: 0px;
border-color: #546C55;
border-style: solid;
TeX: {
Macros: {
bra: ['{\\left\\langle #1\\right|}',1],
ket: ['{\\left| #1\\right\\rangle}',1],
braket: ['\\left\\langle#1|#2\\right\\rangle', 2],
ri: '\\text{i}',
rd: '\\text{d}'
* sidebar.js
* ~~~~~~~~~~
* This script makes the Sphinx sidebar collapsible.
* .sphinxsidebar contains .sphinxsidebarwrapper. This script adds in
* .sphixsidebar, after .sphinxsidebarwrapper, the #sidebarbutton used to
* collapse and expand the sidebar.
* When the sidebar is collapsed the .sphinxsidebarwrapper is hidden and the
* width of the sidebar and the margin-left of the document are decreased.
* When the sidebar is expanded the opposite happens. This script saves a
* per-browser/per-session cookie used to remember the position of the sidebar
* among the pages. Once the browser is closed the cookie is deleted and the
* position reset to the default (expanded).
* :copyright: Copyright 2007-2011 by the Sphinx team.
* :license: BSD, see LICENSE.txt for details.
$(function() {
// global elements used by the functions.
// the 'sidebarbutton' element is defined as global after its
// creation, in the add_sidebar_button function
var bodywrapper = $('.bodywrapper');
var sidebar = $('.sphinxsidebar');
var sidebarwrapper = $('.sphinxsidebarwrapper');
// original margin-left of the bodywrapper and width of the sidebar
// with the sidebar expanded
var bw_margin_expanded = bodywrapper.css('margin-left');
var ssb_width_expanded = sidebar.width();
// margin-left of the bodywrapper and width of the sidebar
// with the sidebar collapsed
var bw_margin_collapsed = '.8em';
var ssb_width_collapsed = '.8em';
// colors used by the current theme
var dark_color = '#AAAAAA';
var light_color = '#CCCCCC';
function sidebar_is_collapsed() {
function toggle_sidebar() {
if (sidebar_is_collapsed())
function collapse_sidebar() {
sidebar.css('width', ssb_width_collapsed);
bodywrapper.css('margin-left', bw_margin_collapsed);
'margin-left': '0',
'height': bodywrapper.height(),
'border-radius': '5px'
sidebarbutton.attr('title', _('Expand sidebar'));
document.cookie = 'sidebar=collapsed';
function expand_sidebar() {
bodywrapper.css('margin-left', bw_margin_expanded);
sidebar.css('width', ssb_width_expanded);;
'margin-left': ssb_width_expanded-12,
'height': bodywrapper.height(),
'border-radius': '0 5px 5px 0'
sidebarbutton.attr('title', _('Collapse sidebar'));
// Math.max(window.pageYOffset - sidebarwrapper.offset().top, 10)});
document.cookie = 'sidebar=expanded';
function add_sidebar_button() {