Add readthedocs yaml configuration file (nest#79)

.readthedocs.yml

@@ -0,0 +1,13 @@
+version: 2
+
+build:
+    os: ubuntu-20.04
+    tools:
+        python: "3.9"
+
+sphinx:
+    configuration: doc/conf.py
+
+python:
+    install:
+    - requirements: doc/requirements.txt

doc/conf.py

@@ -46,6 +46,7 @@
 
 os.system('mkdir _static')
 os.system('install -v -D css/custom.css _static/css/custom.css')
+os.system('install -v -D js/expand_toc_tree.js _static/js/expand_toc_tree.js')
 
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
@@ -115,7 +116,7 @@
     'sphinx.ext.intersphinx',
     'sphinx.ext.todo',
     'sphinx.ext.coverage',
-    'sphinx.ext.mathjax',
+    'sphinx.ext.mathjax'
 ]
 
 autodoc_default_flags = ['private-members', 'show-inheritance']
@@ -177,23 +178,38 @@
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 
-html_theme = 'sphinx_rtd_theme'
+html_theme = "sphinx_rtd_theme"
+html_title = "ODE-toolbox"
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
 # documentation.
 
 html_theme_options = {
     'logo_only': True,
-    'navigation_depth': 2,
-    'collapse_navigation': False
+    'navigation_depth': 1,
+    'collapse_navigation': False,
+    'globaltoc_collapse': True,
+    'globaltoc_maxdepth': 1
 }
+
+
 html_logo = "https://raw.githubusercontent.com/nest/ode-toolbox/master/doc/fig/ode-toolbox-logo.png"
 
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ['css', 'fig']
+html_static_path = ['css', 'fig', 'js', '_static']
+
+# These paths are either relative to html_static_path
+# or fully qualified paths (eg. https://...)
+html_css_files = [
+    'css/custom.css'
+]
+
+html_js_files = [
+    'js/expand_toc_tree.js'
+]
 
 # -- Options for HTMLHelp output ------------------------------------------
 
@@ -216,11 +232,8 @@ def skip(app, what, name, obj, would_skip, options):
     return would_skip
 
 def setup(app):
-    app.add_stylesheet('css/custom.css')
-    app.add_stylesheet('css/pygments.css')
     app.connect("autodoc-skip-member", skip)
 
-
 # -- Options for LaTeX output ---------------------------------------------
 
 latex_elements = {

doc/css/custom.css

@@ -140,4 +140,10 @@ tr.row-odd {
    background-color: #FFFFFF !important;
 }
 
+figure {
+    margin-bottom: 24px !important;
+}
 
+.toctree-expand {
+    display: none !important;
+}

doc/index.rst

@@ -5,7 +5,8 @@ ODE-toolbox
 
 .. toctree::
    :hidden:
-   :maxdepth: 2
+   :maxdepth: 1
+   :tocdepth: 1
 
    index
 

doc/js/expand_toc_tree.js

@@ -0,0 +1,21 @@
+function expandTocTree() {
+    var toctree = document.querySelector('button.toctree-expand');
+    var parentLink = toctree.closest('a');
+    var parentListItem = parentLink.closest('li');
+
+    if (parentLink && parentLink.textContent.includes('ODE-toolbox') && (parentListItem.getAttribute("aria-expanded") === "false" || !parentListItem.hasAttribute("aria-expanded"))) {
+        toctree.focus();
+        toctree.click();
+    }
+}
+
+function hideDeeperTocTreeItems() {
+    var toctree = document.getElementsByClassName('local-toc')[0];
+    const subLists = toctree.querySelectorAll('ul ul ul');
+    subLists.forEach(ul => {
+        ul.style.display = 'none';
+    });
+}
+
+setInterval(expandTocTree, 100);
+setInterval(hideDeeperTocTreeItems, 100);

doc/requirements.txt

@@ -0,0 +1,7 @@
+sympy
+scipy
+numpy
+sphinx
+readthedocs-sphinx-ext
+sphinx-rtd-theme
+sphinx-design

odetoolbox/shapes.py

@@ -114,7 +114,7 @@ def __init__(self, symbol, order, initial_values, derivative_factors, inhom_term
         :param symbol: Symbolic name of the shape without additional qualifiers like prime symbols or similar.
         :param order: Order of the ODE representing the shape.
         :param initial_values: Initial values of the ODE representing the shape. The dict contains :python:`order` many key-value pairs: one for each derivative that occurs in the ODE. The keys are strings created by concatenating the variable symbol with as many single quotation marks (') as the derivation order. The values are SymPy expressions.
-        :param derivative_factors: The factors for the derivatives that occur in the ODE. This list has to contain :path:`order` many values, i.e. one for each derivative that occurs in the ODE. The values have to be in ascending order, i.e. :python:`[c1, c2, c3]` for the given example.
+        :param derivative_factors: The factors for the derivatives that occur in the ODE. This list has to contain :python:`order` many values, i.e. one for each derivative that occurs in the ODE. The values have to be in ascending order, i.e. :python:`[c1, c2, c3]` for the given example.
         :param inhom_term: Inhomogeneous part of the ODE representing the shape, i.e. :python:`c0` for the given example.
         :param nonlin_term: Nonlinear part of the ODE representing the shape, i.e. :python:`x*y + x**2` for the given example.
         """

odetoolbox/system_of_shapes.py

@@ -360,6 +360,7 @@ def get_connected_symbols(self, idx: int) -> List[sympy.Symbol]:
 
            \frac{dx}{dt} &= y\\
            \frac{dy}{dt} &= y' = -\frac{1}{\tau^2} x - \frac{2}{\tau} y
+
         Then ``get_connected_symbols()`` for symbol ``x`` would return ``[x, y]``, and ``get_connected_symbols()`` for ``y`` would return the same.
         """
         N = self.A_.shape[0]