Fix type alias, generics, and example order in documentation (#67)

This PR fixes the following minor errors and aspects in the documentation.
1. The `Smiles` type alias introduced in `parameters.substance`. This
type alias is manually configured in `conf.py`. In order to avoid the
documentation to load all of the attributes and functions of `str`, the
templates were changed slightly to not include those, resulting in the
output shown at the end.
2. The generics in `baybe.utils.basic`. Sphinx behaves weird when using
generics (see sphinx-doc/sphinx#10974). Thus,
an exception was included in the nitpick_ignore dictionary, eliminating
the error.
3. The order of the examples in the table of contents as well as the level of
displayed headings was adjusted

CHANGELOG.md

@@ -14,9 +14,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Renamed `bounds_transform_func` target attribute to `transformation`
 - `Interval.is_bounded` now implements the mathematical definition of boundedness
 - Moved and renamed target transform utility functions
+- Examples have two levels of headings in the table of content
+- Fix orders of examples in table of content
 
 ### Fixed
 - Wrong use of `tolerance` argument in constraints user guide
+- Errors with generics and type aliases in documentation
 
 ### Removed
 - Conda install instructions and version badge

docs/conf.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 # Configuration file for the Sphinx documentation builder.
 #
 # For the full list of built-in configuration values, see the documentation:
@@ -117,6 +119,11 @@
     (r"py:.*", "baybe.constraints.conditions.Condition.__init__"),
     (r"py:.*", "baybe.utils.serialization.SerialMixin.__init__"),
     (r"DeprecationWarning:", ""),
+    # Ignore the generics in utils.basic
+    # Might be able to us a regex here, is done explicitly at the moment for full
+    # transparency.
+    (r"py:class", "baybe.utils.basic._T"),
+    (r"py:class", "baybe.utils.basic._U"),
 ]
 
 # -- Options for HTML output -------------------------------------------------
@@ -214,6 +221,7 @@
 if "BAYBE_DOCS_LINKCHECK_IGNORE" in os.environ:
     linkcheck_ignore = ["https://emdgroup.github.io/baybe/"]
 
+autodoc_type_aliases = {"Smiles": "Smiles"}
 
 # Everything in the module has the prefix baybe
 modindex_common_prefix = ["baybe."]

docs/scripts/convert_code_to_documentation.py

@@ -85,13 +85,26 @@ def create_example_documentation(example_dest_dir: str):
     # Copy the examples folder in the destination directory
     shutil.copytree("examples", examples_directory)
 
-    # List all directories in the examples folder
-    ex_directories = [d for d in examples_directory.iterdir() if d.is_dir()]
-
     # For the toctree of the top level example folder, we need to keep track of all
     # folders. We thus write the header here and populate it during the execution of the
     # examples
-    ex_file = "# Examples\n\nThese examples show how to use BayBE.\n\n```{toctree}\n"
+    ex_file = """# Examples\n\n```{toctree}\n:maxdepth: 2\n\n"""
+
+    # List all directories in the examples folder
+    ex_directories = [d for d in examples_directory.iterdir() if d.is_dir()]
+
+    # This list contains the order of the examples as we want to have them in the end.
+    # The examples that should be the first ones are already included here and skipped
+    # later on. ALl other are just included.
+    ex_order = [
+        "Basics<Basics/Basics>\n",
+        "Searchspaces<Searchspaces/Searchspaces>\n",
+        "Constraints Discrete<Constraints_Discrete/Constraints_Discrete>\n",
+        "Constraints Continuous<Constraints_Continuous/Constraints_Continuous>\n",
+        "Multi Target<Multi_Target/Multi_Target>\n",
+        "Serialization<Serialization/Serialization>\n",
+        "Custom Surrogates<Custom_Surrogates/Custom_Surrogates>\n",
+    ]
 
     # Iterate over the directories.
     for sub_directory in (pbar := tqdm(ex_directories)):
@@ -100,11 +113,14 @@ def create_example_documentation(example_dest_dir: str):
         folder_name = sub_directory.stem
         formatted = " ".join(word.capitalize() for word in folder_name.split("_"))
 
-        # Attach the link to the folder to the top level toctree.
-        ex_file += formatted + f"<{folder_name}/{folder_name}>\n"
+        # Create the link to the folder to the top level toctree.
+        ex_file_entry = formatted + f"<{folder_name}/{folder_name}>\n"
+        # Add it to the list of examples if it is not already contained
+        if ex_file_entry not in ex_order:
+            ex_order.append(ex_file_entry)
 
         # We need to create a file for the inclusion of the folder
-        subdir_toctree = f"# {folder_name}\n\n" + "```{toctree}\n"
+        subdir_toctree = f"# {folder_name}\n\n" + "```{toctree}\n:maxdepth: 2\n\n"
 
         # Set description of progressbar
         pbar.set_description("Overall progress")
@@ -175,6 +191,8 @@ def create_example_documentation(example_dest_dir: str):
         ) as f:
             f.write(subdir_toctree)
 
+    # Append the ordered list of examples to the file for the top level folder
+    ex_file += "".join(ex_order)
     # Write last line of top level toctree file and write the file
     ex_file += "```"
     with open(

docs/templates/custom-attribute-template.rst

@@ -0,0 +1,7 @@
+{{ fullname | escape | underline}}
+
+.. currentmodule:: {{ module }}
+
+{% if not fullname in ("Smiles") %}
+.. auto{{ objtype }}:: {{ objname }}
+{% endif %}

docs/templates/custom-module-template.rst

@@ -7,7 +7,8 @@
    .. rubric:: Module Attributes
 
    .. autosummary::
-      :toctree:                                  
+      :toctree: 
+      :template: custom-attribute-template.rst                               
    {% for item in attributes %}
       {{ item }}
    {%- endfor %}