Adding some docs (#529)

* Adds documentation for Objective. * Remove unnecessary method. * Fixed bug in Objective.copy(). * Fix some pre-commit issues.
facebookresearch · Jun 21, 2023 · 5450659 · 5450659
1 parent 28fc60b
commit 5450659
Show file tree

Hide file tree

Showing 11 changed files with 344 additions and 78 deletions.
diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -18,7 +18,7 @@
 import os
 import sys
 
-sys.path.insert(0, os.path.abspath(".."))
+sys.path.insert(0, os.path.abspath(os.path.join("..", "..")))
 
 # -- Project information -----------------------------------------------------
 
@@ -71,3 +71,14 @@
 # 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 = ["_static"]
+
+
+def skip_undocumented(app, what, name, obj, skip, options):
+    exclusions = ["__weakref__", "__module__"]
+    if not skip and obj.__doc__ is None and name not in exclusions:
+        return True
+    return None
+
+
+def setup(app):
+    app.connect("autodoc-skip-member", skip_undocumented)
diff --git a/docs/source/core.rst b/docs/source/core.rst
@@ -3,7 +3,7 @@ Core Module
 
 Objective
 ---------
-An objective function to optimize. 
+An objective function to optimize (see :class:`theseus.Objective`). 
 
 Cost Function
 -------------
@@ -25,4 +25,14 @@ Reference
     :nosignatures:
 
     theseus.Objective
+        :no-undoc-members:
+        :nosignatures:
+    theseus.Objective.add
+    theseus.Objective.error
+    theseus.Objective.error_metric    
+    theseus.Objective.update
+    theseus.Objective.retract_vars_sequence
+    theseus.CostFunction
+        :no-undoc-members:
+        :nosignatures:
     theseus.Variable
diff --git a/docs/source/generated/theseus.CostFunction.rst b/docs/source/generated/theseus.CostFunction.rst
@@ -0,0 +1,16 @@
+theseus.CostFunction
+====================
+
+.. currentmodule:: theseus
+
+.. autoclass:: CostFunction
+
+
+   .. automethod:: __init__
+
+
+
+
+
+
+
diff --git a/docs/source/generated/theseus.Objective.add.rst b/docs/source/generated/theseus.Objective.add.rst
@@ -0,0 +1,6 @@
+theseus.Objective.add
+=====================
+
+.. currentmodule:: theseus
+
+.. automethod:: Objective.add
diff --git a/docs/source/generated/theseus.Objective.error.rst b/docs/source/generated/theseus.Objective.error.rst
@@ -0,0 +1,6 @@
+theseus.Objective.error
+=======================
+
+.. currentmodule:: theseus
+
+.. automethod:: Objective.error
diff --git a/docs/source/generated/theseus.Objective.retract_vars_sequence.rst b/docs/source/generated/theseus.Objective.retract_vars_sequence.rst
@@ -0,0 +1,6 @@
+theseus.Objective.retract\_vars\_sequence
+=========================================
+
+.. currentmodule:: theseus
+
+.. automethod:: Objective.retract_vars_sequence
diff --git a/docs/source/generated/theseus.Objective.rst b/docs/source/generated/theseus.Objective.rst
@@ -13,41 +13,29 @@
 
    .. autosummary::
 
-      ~Objective.__init__
       ~Objective.add
       ~Objective.copy
       ~Objective.dim
-      ~Objective.disable_vectorization
       ~Objective.erase
       ~Objective.error
-      ~Objective.error_squared_norm
+      ~Objective.error_metric
       ~Objective.get_aux_var
       ~Objective.get_cost_function
-      ~Objective.get_cost_function_name
       ~Objective.get_functions_connected_to_aux_var
       ~Objective.get_functions_connected_to_optim_var
       ~Objective.get_optim_var
       ~Objective.has_aux_var
       ~Objective.has_cost_function
       ~Objective.has_optim_var
-      ~Objective.retract_optim_vars
+      ~Objective.retract_vars_sequence
       ~Objective.size
       ~Objective.size_aux_vars
       ~Objective.size_cost_functions
       ~Objective.size_variables
-      ~Objective.to
       ~Objective.update
-      ~Objective.update_vectorization_if_needed
 
 
 
 
 
-   .. rubric:: Attributes
-
-   .. autosummary::
-
-      ~Objective.batch_size
-      ~Objective.vectorized
-
 
diff --git a/docs/source/generated/theseus.Objective.update.rst b/docs/source/generated/theseus.Objective.update.rst
@@ -0,0 +1,6 @@
+theseus.Objective.update
+========================
+
+.. currentmodule:: theseus
+
+.. automethod:: Objective.update
diff --git a/docs/source/generated/theseus.Variable.rst b/docs/source/generated/theseus.Variable.rst
@@ -9,26 +9,8 @@
    .. automethod:: __init__
 
 
-   .. rubric:: Methods
-
-   .. autosummary::
-
-      ~Variable.__init__
-      ~Variable.copy
-      ~Variable.to
-      ~Variable.update
-
-
-
-
 
-   .. rubric:: Attributes
 
-   .. autosummary::
 
-      ~Variable.device
-      ~Variable.dtype
-      ~Variable.ndim
-      ~Variable.shape
 
 
diff --git a/theseus/core/cost_function.py b/theseus/core/cost_function.py
@@ -62,6 +62,8 @@ def masked_jacobians(
 # jacobian of the error, by implementing abstract methods
 # `error` and `jacobians`, respectively.
 class CostFunction(TheseusFunction, abc.ABC):
+    """A cost function in a differentiable optimization problem."""
+
     def __init__(
         self,
         cost_weight: CostWeight,