Doc additions, API updates, start using doctest.

doc/_templates/custom-class-template.rst

@@ -0,0 +1,29 @@
+{{ fullname | escape | underline}}
+
+.. currentmodule:: {{ module }}
+
+.. autoclass:: {{ objname }}
+   :members:
+   :special-members: __init__
+
+   {% block methods %}
+   {% if methods %}
+   .. rubric:: {{ _('Methods') }}
+
+   .. autosummary::
+   {% for item in methods %}
+      ~{{ name }}.{{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block attributes %}
+   {% if attributes %}
+   .. rubric:: {{ _('Attributes') }}
+
+   .. autosummary::
+   {% for item in attributes %}
+      ~{{ name }}.{{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}

doc/_templates/custom-enum-template.rst

@@ -0,0 +1,6 @@
+{{ fullname | escape | underline}}
+
+.. currentmodule:: {{ module }}
+
+.. autoclass:: {{ objname }}
+

doc/api_exsys.rst

@@ -5,8 +5,30 @@ Expression system
 
 .. currentmodule:: heyoka
 
+Classes
+-------
+
 .. autosummary::
    :toctree: autosummary_generated
+   :template: custom-class-template.rst
 
    expression
+   dtens
+
+Functions
+---------
+
+.. autosummary::
+   :toctree: autosummary_generated
+
    make_vars
+   diff_tensors
+
+Enums
+-----
+
+.. autosummary::
+   :toctree: autosummary_generated
+   :template: custom-enum-template.rst
+
+   diff_args

doc/breaking_changes.rst

@@ -24,7 +24,9 @@ input arguments, turned out to be in practice confusing and a source of bugs.
 The affected APIs include:
 
 - :ref:`compiled functions <cfunc_tut>`, which now require the list of input
-  variables to be always supplied by the user.
+  variables to be always supplied by the user;
+- :func:`~heyoka.diff_tensors()`, which now requires an explicit list of differentiation
+  arguments to be always provided by the user.
 
 The tutorials and the documentation have been updated accordingly.
 

doc/changelog.rst

@@ -25,6 +25,10 @@ New
 Changes
 ~~~~~~~
 
+- **BREAKING**: it is now mandatory to supply a list of differentiation
+  arguments to :func:`~heyoka.diff_tensors()`
+  (`#164 <https://github.com/bluescarni/heyoka.py/pull/164>`__).
+  This is a :ref:`breaking change <bchanges_4_0_0>`.
 - **BREAKING**: :ref:`compiled functions <cfunc_tut>` now require
   the list of input variables to be always supplied by the user
   (`#162 <https://github.com/bluescarni/heyoka.py/pull/162>`__).

doc/conf.py

@@ -36,6 +36,7 @@
               "sphinx.ext.intersphinx",
               "sphinx.ext.autodoc",
               "sphinx.ext.autosummary",
+              "sphinx.ext.doctest",
               ]
 
 intersphinx_mapping = {

doc/index.md

@@ -104,7 +104,7 @@ examples_others
 :maxdepth: 2
 :caption: API reference
 
-api_integrators
 api_exsys
+api_integrators
 api_lagham
 ```

heyoka/_test_dtens.py

@@ -51,7 +51,7 @@ def test_basic(self):
         self.assertEqual(len(dt), 0)
         self.assertEqual(dt.args, [])
         self.assertEqual(dt.nouts, 0)
-        self.assertEqual(dt.nvars, 0)
+        self.assertEqual(dt.nargs, 0)
         self.assertEqual(dt.order, 0)
         with self.assertRaises(KeyError) as cm:
             dt[1, 2, 3]
@@ -97,21 +97,21 @@ def test_basic(self):
         self.assertEqual(len(dt2), 0)
         self.assertEqual(dt2.args, [])
         self.assertEqual(dt2.nouts, 0)
-        self.assertEqual(dt2.nvars, 0)
+        self.assertEqual(dt2.nargs, 0)
         self.assertEqual(dt2.order, 0)
 
         dt2 = copy(dt)
         self.assertEqual(len(dt2), 0)
         self.assertEqual(dt2.args, [])
         self.assertEqual(dt2.nouts, 0)
-        self.assertEqual(dt2.nvars, 0)
+        self.assertEqual(dt2.nargs, 0)
         self.assertEqual(dt2.order, 0)
 
         dt2 = deepcopy(dt)
         self.assertEqual(len(dt2), 0)
         self.assertEqual(dt2.args, [])
         self.assertEqual(dt2.nouts, 0)
-        self.assertEqual(dt2.nvars, 0)
+        self.assertEqual(dt2.nargs, 0)
         self.assertEqual(dt2.order, 0)
 
     def test_diff_tensors(self):
@@ -125,7 +125,7 @@ def test_diff_tensors(self):
         self.assertEqual(len(dt), 3)
         self.assertEqual(dt.args, [x, y])
         self.assertEqual(dt.nouts, 1)
-        self.assertEqual(dt.nvars, 2)
+        self.assertEqual(dt.nargs, 2)
         self.assertEqual(dt.order, 1)
         self.assertEqual(dt[0, 0, 0], x + y)
         self.assertEqual(dt[1], ([0, 1, 0], expression(1.0)))
@@ -154,7 +154,7 @@ def test_diff_tensors(self):
         self.assertEqual(len(dt), 3)
         self.assertEqual(dt.args, [x])
         self.assertEqual(dt.nouts, 1)
-        self.assertEqual(dt.nvars, 1)
+        self.assertEqual(dt.nargs, 1)
         self.assertEqual(dt.order, 2)
         self.assertEqual(dt[0, 0], x + y)
         self.assertEqual(dt[0, 1], expression(1.0))
@@ -166,7 +166,7 @@ def test_diff_tensors(self):
         self.assertEqual(len(dt), 3)
         self.assertEqual(dt.args, [par[0]])
         self.assertEqual(dt.nouts, 1)
-        self.assertEqual(dt.nvars, 1)
+        self.assertEqual(dt.nargs, 1)
         self.assertEqual(dt.order, 2)
         self.assertEqual(dt[0, 0], x + y + 2.0 * par[0])
         self.assertEqual(dt[0, 1], expression(2.0))
@@ -176,7 +176,7 @@ def test_diff_tensors(self):
         self.assertEqual(len(dt), 10)
         self.assertEqual(dt.args, [x, y, par[0]])
         self.assertEqual(dt.nouts, 1)
-        self.assertEqual(dt.nvars, 3)
+        self.assertEqual(dt.nargs, 3)
         self.assertEqual(dt.order, 2)
         self.assertEqual(dt[0, 0, 0, 0], x + y + 2.0 * par[0])
         self.assertEqual(dt[0, 1, 0, 0], expression(1.0))
@@ -190,7 +190,7 @@ def test_diff_tensors(self):
         self.assertEqual(len(dt), 10)
         self.assertEqual(dt.args, [x, y, par[0]])
         self.assertEqual(dt.nouts, 1)
-        self.assertEqual(dt.nvars, 3)
+        self.assertEqual(dt.nargs, 3)
         self.assertEqual(dt.order, 2)
         self.assertEqual(dt[0, 0, 0, 0], x + y + 2.0 * par[0])
         self.assertEqual(dt[0, 1, 0, 0], expression(1.0))
@@ -204,7 +204,7 @@ def test_diff_tensors(self):
         self.assertEqual(len(dt), 10)
         self.assertEqual(dt.args, [x, y, par[0]])
         self.assertEqual(dt.nouts, 1)
-        self.assertEqual(dt.nvars, 3)
+        self.assertEqual(dt.nargs, 3)
         self.assertEqual(dt.order, 2)
         self.assertEqual(dt[0, 0, 0, 0], x + y + 2.0 * par[0])
         self.assertEqual(dt[0, 1, 0, 0], expression(1.0))
@@ -219,7 +219,7 @@ def test_diff_tensors(self):
         self.assertEqual(len(dt), 10)
         self.assertEqual(dt.args, [x, y, par[0]])
         self.assertEqual(dt.nouts, 1)
-        self.assertEqual(dt.nvars, 3)
+        self.assertEqual(dt.nargs, 3)
         self.assertEqual(dt.order, 2)
         self.assertEqual(dt[0, 0, 0, 0], x + y + 2.0 * par[0])
         self.assertEqual(dt[0, 1, 0, 0], expression(1.0))