Adapt sphinx docs and improve some docstrings

derotation/analysis/derotate_incremental_rotations.py

@@ -12,6 +12,10 @@
 
 
 class DerotateIncremental(DerotationPipeline):
+    """Derotate the image stack that was acquired using the incremental
+    rotation method.
+    """
+
     def __init__(self, *args, **kwargs):
         """Derotate the image stack that was acquired using the incremental
         rotation method.

derotation/analysis/derotation_pipeline.py

@@ -22,6 +22,10 @@
 
 
 class DerotationPipeline:
+    """DerotationPipeline is a class that derotates an image stack
+    acquired with a rotating sample under a microscope.
+    """
+
     def __init__(self, config_name):
         """DerotationPipeline is a class that derotates an image stack
         acquired with a rotating sample under a microscope.
@@ -95,17 +99,18 @@ def load_data(self):
         Data is stored in the class attributes.
 
         What is loaded:
-        - image stack (tif file)
-        - direction and speed of rotation (from randperm file, uses
-        custom_data_loaders.read_randomized_stim_table)
-        - analog signals (from aux file, uses
-        custom_data_loaders.get_analog_signals). Measured in
-        "clock_time", they are:
-            - frame clock: on during acquisition of a new frame, off otherwise
-            - line clock: on during acquisition of a new line, off otherwise
-            - full rotation: when the motor is rotating
-            - rotation ticks: peaks at every given increment of rotation
-        - various parameters from config file
+            * various parameters from config file
+            * image stack (tif file)
+            * direction and speed of rotation (from randperm file, uses  \
+            custom_data_loaders.read_randomized_stim_table)
+            * analog signals \
+            (from aux file, uses `custom_data_loaders.get_analog_signals`)
+
+        Analog signals are four files, measured in "clock_time":
+            * frame clock: on during acquisition of a new frame, off otherwise
+            * line clock: on during acquisition of a new line, off otherwise
+            * full rotation: when the motor is rotating
+            * rotation ticks: peaks at every given increment of rotation
 
         The data is loaded using the custom_data_loaders module, which are
         sepecific to the setup used in the lab. Please edit them to load

docs/source/api_index.rst

@@ -1,25 +1,16 @@
 API
-===
+====
 
-math
-----
+Full derotation
+---------------
 
-.. currentmodule:: derotation.math
+.. currentmodule:: derotation.analysis.derotation_pipeline
 
-.. autosummary::
-    :toctree: api_generated
-    :template: function.rst
+.. autoclass:: DerotationPipeline
 
-    add_two_integers
-    subtract_two_integers
+Incremental derotation
+----------------------
 
-greetings
----------
+.. currentmodule:: derotation.analysis.derotate_incremental_rotations
 
-.. currentmodule:: derotation.greetings
-
-.. autosummary::
-    :toctree: api_generated
-    :template: class.rst
-
-    Greetings
+.. autoclass:: DerotateIncremental

docs/source/conf.py

@@ -25,6 +25,7 @@
 author = "Laura Porta"
 try:
     release = setuptools_scm.get_version(root="../..", relative_to=__file__)
+    release = release.split("+")[0]
 except LookupError:
     # if git is not initialised, still allow local build
     # with a dummy version
@@ -34,15 +35,18 @@
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
 
 extensions = [
-    "sphinx.ext.napoleon",
-    "sphinx.ext.autodoc",
     "sphinx.ext.githubpages",
-    "sphinx_autodoc_typehints",
+    "sphinx.ext.autodoc",
     "sphinx.ext.autosummary",
     "sphinx.ext.viewcode",
     "sphinx.ext.intersphinx",
+    "sphinx.ext.napoleon",
     "myst_parser",
+    "numpydoc",
     "nbsphinx",
+    "sphinx_autodoc_typehints",
+    "sphinx_design",
+    "sphinxarg.ext",
 ]
 
 # Configure the myst parser to enable cool markdown features
@@ -70,7 +74,24 @@
 
 # Automatically generate stub pages for API
 autosummary_generate = True
-autodoc_default_flags = ["members", "inherited-members"]
+numpydoc_class_members_toctree = False  # stops stubs warning
+#toc_object_entries_show_parents = "all"
+html_show_sourcelink = False
+
+#html_sidebars = {  this is not working...
+#  "index": [],
+#  "**": [],
+#}
+
+autodoc_default_options = {
+    'members': True,
+    "member-order": "bysource",
+    'special-members': False,
+    'private-members': False,
+    'inherited-members': False,
+    'undoc-members': True,
+    'exclude-members': "",
+}
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.

docs/source/index.rst

@@ -10,35 +10,9 @@ Welcome to derotation's documentation!
    :maxdepth: 2
    :caption: Contents:
 
-   getting_started
    api_index
 
-By default the documentation includes the following sections:
 
-* Getting started. Here you could describe the basic functionalities of your package. To modify this page, edit the file ``docs/source/getting_started.md``.
-* API: here you can find the auto-generated documentation of your package, which is based on the docstrings in your code. To modify which modules/classes/functions are included in the API documentation, edit the file ``docs/source/api_index.rst``.
-
-You can create additional sections with narrative documentation,
-by adding new ``.md`` or ``.rst`` files to the ``docs/source`` folder.
-These files shoult start with a level-1 (H1) header,
-which will be used as the section title. Sub-sections can be created
-with lower-level headers (H2, H3, etc.) within the same file.
-
-To include a section in the rendered documentation,
-add it to the ``toctree`` directive in this (``docs/source/index.rst``) file.
-
-For example, you could create a ``docs/source/installation.md`` file
-and add it to the ``toctree`` like this:
-
-.. code-block:: rst
-
-   .. toctree::
-      :maxdepth: 2
-      :caption: Contents:
-
-      getting_started
-      installation
-      api_index
 
 Index & Search
 --------------