manual module listing

.gitignore

@@ -81,6 +81,13 @@ cover/
 # Sphinx documentation
 docs/_build/
 docs/_autosummary/
+docs/api_reference/_autosummary/
+docs/core/_autosummary/
+docs/gui/_autosummary/
+docs/logic/_autosummary/
+docs/tools/_autosummary/
+docs/tasks/_autosummary/
+docs/util/_autosummary/
 docs/_static/
 
 # Jupyter Notebook

calculate_documentation_coverage.py

@@ -5,11 +5,13 @@ class PublicMethodVisitor(ast.NodeVisitor):
     def __init__(self):
         self.public_methods = 0
         self.documented_methods = 0
+        self.enclosing_scopes = []
 
     def visit_FunctionDef(self, node):
         if not node.name.startswith("__") and (not node.name.startswith("_") or "__all__" in self.enclosing_scopes):
             self.public_methods += 1
-            if node.body and isinstance(node.body[0], ast.Expr):
+            # Check if the first node in the function body is a string (which would be a docstring)
+            if node.body and isinstance(node.body[0], (ast.Expr, ast.Constant)) and isinstance(node.body[0].value, (ast.Str, ast.Constant)):
                 self.documented_methods += 1
         self.generic_visit(node)
 
@@ -19,10 +21,13 @@ def visit_ClassDef(self, node):
         self.enclosing_scopes.pop()
 
     def visit_Module(self, node):
-        if hasattr(node, "__all__"):
-            self.enclosing_scopes = node.__all__
-        else:
-            self.enclosing_scopes = []
+        # Initialize enclosing scopes, and handle __all__ if present
+        self.enclosing_scopes = []
+        if hasattr(node, 'body'):
+            for item in node.body:
+                if isinstance(item, ast.Assign) and any(target.id == '__all__' for target in item.targets if isinstance(target, ast.Name)):
+                    self.enclosing_scopes = [name.s for name in item.value.elts if isinstance(name, ast.Str)]
+        self.generic_visit(node)
 
 def parse_files(directory):
     public_methods = 0
@@ -44,7 +49,9 @@ def parse_files(directory):
     return public_methods, documented_methods
 
 # Specify the directory containing your Python files
-directory = "../src/qudi/"
+directory = os.path.join("src", "qudi")
+
+
 
 # Call the function to parse files and calculate coverage
 total_methods, documented_methods = parse_files(directory)

docs/404.rst

@@ -1,3 +1,6 @@
+
+.. _error:
+
 Uh… have you tried turning it off and on again?
 ===============================================
 

docs/Makefile

@@ -5,20 +5,23 @@
 # from the environment for the first two.
 SPHINXOPTS    ?= --jobs=auto
 SPHINXBUILD   ?= sphinx-build
+SPHINXAUTOBUILD ?= sphinx-autobuild
 SOURCEDIR     = .
 BUILDDIR      = _build
 
 # Put it first so that "make" without argument is like "make help".
 help:
 	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
 
-.PHONY: help Makefile clean
+.PHONY: help Makefile clean autobuild
 
 # Catch-all target: route all unknown targets to Sphinx using the new
 # "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
 %: Makefile
-	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+	@$(SPHINXAUTOBUILD) "$(SOURCEDIR)" "$(BUILDDIR)" --watch "$(SOURCEDIR)" --open-browser
+
 
 clean:
 	@echo "Cleaning up build directories..."
-	rm -rf $(BUILDDIR) _autosummary
+	rm -rf $(BUILDDIR) _autosummary
+

docs/api_reference/index.rst

@@ -0,0 +1,18 @@
+.. _api:
+
+API Reference
+=============
+
+.. toctree::
+    :maxdepth: 6
+    :hidden:
+
+
+    ../core/index
+    ../gui/index 
+    ../logic/index 
+    ../tasks/index
+    ../tools/index
+    ../util/index
+
+.. include::  ../core/index.rst

docs/conf.py

@@ -26,11 +26,10 @@
     'sphinx.ext.autodoc',
     'sphinx.ext.autosummary',
     'sphinx.ext.viewcode',
-    'sphinx_rtd_dark_mode',
     'sphinx.ext.intersphinx',
-    'sphinx.ext.doctest', 
-    'sphinx.ext.coverage', 
-    'sphinx.ext.napoleon',
+    'sphinx.ext.doctest',
+    "sphinx_design", 
+    'sphinx.ext.coverage'
 ]
 intersphinx_mapping = {
     'PySide2': (
@@ -52,13 +51,38 @@
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
 
 html_theme = 'pydata_sphinx_theme'
-# html_theme = 'sphinx_book_theme'
-# html_theme = 'sphinx_rtd_theme'
+html_logo = "../src/qudi/artwork/logo/logo_qudi.ico"
 html_theme_options = {
+    "logo": {
+        "text": "Qudi-Core",
+        "image_dark": "../src/qudi/artwork/logo/logo_qudi.ico",
+    },
+    'dark_mode': True,
+    "navbar_start": ["navbar-logo"],
+    "navbar_center": ["navbar-nav"],
+    "navbar_end": ["navbar-icon-links"],
+    "navbar_persistent": ["theme-switcher", "search-button"],
+    "footer_start": ["copyright", "sphinx-version"],
+    "footer_end": ["theme-version"],
+    "show_toc_level": 1,
+    "show_nav_level": 4,
+    "collapse_navigation": True,
+    "sidebar_hide_name": False,
     'navigation_with_keys': False,  # See https://github.com/pydata/pydata-sphinx-theme/issues/1492
 }
-html_static_path = []  # Normally defaults to '_static' but we don't have any static files.
-default_dark_mode = False  # For sphinx_rtd_dark_mode. Dark mode needs tweaking so not defaulting to it yet.
+
+html_sidebars = {
+    "**": ["sidebar-nav-bs", "sidebar-ethical-ads"]
+}
+html_static_path = ['_static']
+# html_css_files = [
+#     'custom.css',
+# ]
+
+
+
+
+default_dark_mode = True  # For sphinx_rtd_dark_mode. Dark mode needs tweaking so not defaulting to it yet.
 
 numpydoc_show_class_members = False
 numpydoc_show_inherited_class_members = False
@@ -67,18 +91,24 @@
 # Example autodoc settings
 autodoc_default_options = {
     'members': True,    # Document all members (methods and attributes)
-    'undoc-members': True,   # Include members without docstrings
-    'show-inheritance': True,   # Show inheritance links
+    'undoc-members': False,   # Include members without docstrings
+    'show-inheritance': True,
+    'inherited-members': False   # Show inheritance links
     # Other options as needed
 }
 
-napoleon_numpy_docstring = True
-napoleon_google_docstring = False
-napoleon_include_init_with_doc = True
-napoleon_include_private_with_doc = False
-napoleon_include_special_with_doc = True
-napoleon_use_param = True
-napoleon_use_rtype = True
+intersphinx_mapping = {
+    'iqo': ('https://qudi-iqo-modules.readthedocs.io/en/george/index.html', None),
+}
+
+
+# napoleon_numpy_docstring = True
+# napoleon_google_docstring = False
+# napoleon_include_init_with_doc = True
+# napoleon_include_private_with_doc = False
+# napoleon_include_special_with_doc = True
+# napoleon_use_param = True
+# napoleon_use_rtype = True
 
 
 # This gives the full name of the inherited classes in the documentation. It would be better if we could

docs/core/index.rst

@@ -0,0 +1,33 @@
+Core
+====
+
+.. autosummary::
+    :caption: Qudi Core
+    :toctree: _autosummary
+
+    :recursive:
+    :nosignatures:
+
+
+
+    qudi.core.config.config
+    qudi.core.config.file_handler
+    qudi.core.config.schema
+    qudi.core.config.validator
+    qudi.core.gui.gui
+    qudi.core.logger.handlers
+    qudi.core.logger.records_model
+    qudi.core.application
+    qudi.core.configoption
+    qudi.core.connector
+    qudi.core.interface 
+    qudi.core.meta
+    qudi.core.module
+    qudi.core.modulemanager
+    qudi.core.parentpoller
+    qudi.core.qudikernel
+    qudi.core.servers
+    qudi.core.services
+    qudi.core.statusvariable
+    qudi.core.threadmanager
+    qudi.core.watchdog

docs/core_elements/data_storage.rst

@@ -2,6 +2,8 @@
 
 --------------
 
+.. _data_storage:
+
 Data storage with qudi
 ======================
 

docs/design_concepts/config_options.rst

@@ -1,24 +1,25 @@
-`index <../index.rst>`__
 
 --------------
 
+.. _config_options:
+
 Configuration Options
 =====================
 
-When working with `measurement modules <measurement_modules.rst>`__
+When working with :ref:`measurement modules <measurement_modules>`
 (hardware/logic/GUI) you may want to give the user the opportunity to
 statically configure certain aspects of the measurement module.
 
-| `Static configuration <configuration.rst>`__ in qudi is generally
+| :ref:`Static configuration <configuration>` in qudi is generally
   handled via a YAML configuration file that is read and parsed during
   the application startup process.
-| All `measurement modules <measurement_modules.rst>`__ included in the
+| All :ref:`measurement modules <measurement_modules>` included in the
   qudi session are declared in this file (among other things). But apart
   from the mandatory properties you can declare any number of additional
   properties inside the ``options`` property for each measurement
   module.
-| Please refer to the `qudi configuration
-  documentation <configuration.rst>`__ for more details on config files.
+| Please refer to the :ref:`qudi configuration
+  documentation <configuration>` for more details on config files.
 
 A measurement module constant that is automatically initialized from the
 qudi configuration is called a “configuration option” or “config
@@ -39,7 +40,7 @@ members and prevent each measurement module to implement their own
 solution, qudi provides the meta object
 ``qudi.core.configoption.ConfigOption``.
 
-When implementing a `measurement module <measurement_modules.rst>`__
+When implementing a :ref:`measurement_module <measurement_modules>`
 (hardware/logic/GUI) you can simply instantiate ``ConfigOption`` class
 variables. These meta objects will be transformed into regular variable
 members of your measurement module instances and can be used like any
@@ -86,7 +87,7 @@ The corresponding module section in the config file would look like:
                ...
        ...
 
-name
+Name
 ~~~~
 
 Please note here that the variable name in the measurement module
@@ -97,7 +98,7 @@ argument specifies the field name of the config option in the qudi
 configuration and can be any YAML-compatible string as long as it is
 unique within a measurement module.
 
-default
+Default
 ~~~~~~~
 
 | This example is also defining an optional ``default`` value for the
@@ -110,29 +111,29 @@ default
   initialization if the corresponding field is not specified in the qudi
   configuration.
 
-missing
+Missing
 ~~~~~~~
 
 | The optional ``missing`` argument can be used to define the behaviour
   in case the config option is missing from the configuration and has a
   default value. Ignored for non-optional config options.
 | Possible argument values are:
 
-+---------+------------------------------------------------------------+
-| value   | effect                                                     |
-+=========+============================================================+
-| ``'not  | Silently use the default value.                            |
-| hing'`` |                                                            |
-+---------+------------------------------------------------------------+
-| ``'     | Use default value but also logs an info message about the  |
-| info'`` | missing config option.                                     |
-+---------+------------------------------------------------------------+
-| ``'     | Use default value but also logs a warning about the        |
-| warn'`` | missing config option.                                     |
-+---------+------------------------------------------------------------+
-| ``'e    | Fail to initialize the module with an exception. Same as   |
-| rror'`` | for non-optional config options.                           |
-+---------+------------------------------------------------------------+
++--------------+------------------------------------------------------------+
+| value        | effect                                                     |
++==============+============================================================+
+| ``nothing``  | Silently use the default value.                            |
+|              |                                                            |
++--------------+------------------------------------------------------------+
+|   ``info``   | Use default value but also logs an info message about the  |
+|              | missing config option.                                     |
++--------------+------------------------------------------------------------+
+|   ``warn``   | Use default value but also logs a warning about the        |
+|              | missing config option.                                     |
++--------------+------------------------------------------------------------+
+|    ``error`` | Fail to initialize the module with an exception. Same as   |
+|              | for non-optional config options.                           |
++--------------+------------------------------------------------------------+
 
 checker
 ~~~~~~~
@@ -190,5 +191,3 @@ above also shows), you could combine that with the ``@staticmethod``
 decorator. But this is not necessary and just good style.
 
 --------------
-
-`index <../index.rst>`__