chore(docs): nice looking docs

docs/source/_templates/module.rst_t

@@ -0,0 +1,10 @@
+{%- set qbasename = "``" + basename + "``" -%}
+
+{%- if show_headings %}
+{{- [qbasename, "module"] | join(' ') | heading }}
+
+{% endif -%}
+.. automodule:: {{ qualname }}
+{%- for option in automodule_options %}
+   :{{ option }}:
+{%- endfor %}

docs/source/_templates/package.rst_t

@@ -0,0 +1,60 @@
+{%- macro automodule(modname, options) -%}
+.. automodule:: {{ modname }}
+{%- for option in options %}
+   :{{ option }}:
+{%- endfor %}
+{%- endmacro %}
+
+{%- set qpkgname = "``" + pkgname + "``" -%}
+
+{%- macro toctree(docnames) -%}
+.. toctree::
+   :maxdepth: {{ maxdepth }}
+{% for docname in docnames %}
+   {{ docname }}
+{%- endfor %}
+{%- endmacro %}
+
+{%- if is_namespace %}
+{{- [qpkgname, "namespace"] | join(" ") | heading }}
+{% else %}
+{{- [qpkgname, "package"] | join(" ") | heading }}
+{% endif %}
+
+{%- if is_namespace %}
+.. py:module:: {{ pkgname }}
+{% endif %}
+
+{%- if modulefirst and not is_namespace %}
+{{ automodule(pkgname, automodule_options) }}
+{% endif %}
+
+{%- if subpackages %}
+Subpackages
+-----------
+
+{{ toctree(subpackages) }}
+{% endif %}
+
+{%- if submodules %}
+Submodules
+----------
+{% if separatemodules %}
+{{ toctree(submodules) }}
+{% else %}
+{%- for submodule in submodules %}
+{%- set qsubmodule = "``" + submodule + "``" -%}
+{% if show_headings %}
+{{- [qsubmodule, "module"] | join(" ") | heading(2) }}
+{% endif %}
+{{ automodule(submodule, automodule_options) }}
+{% endfor %}
+{%- endif %}
+{%- endif %}
+
+{%- if not modulefirst and not is_namespace %}
+Module contents
+---------------
+
+{{ automodule(pkgname, automodule_options) }}
+{% endif %}

docs/source/conf.py

@@ -8,9 +8,12 @@
 
 from datetime import date
 
+from differt import __version__
+
 project = "DiffeRT"
-copyright = f"{date.today().year}, Jérome Eertmans"
+copyright = f"2023-{date.today().year}, Jérome Eertmans"
 author = "Jérome Eertmans"
+version = __version__
 
 # -- General configuration ---------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
@@ -40,6 +43,9 @@
 
 suppress_warnings = ["mystnb.unknown_mime_type"]
 
+add_module_names = False
+add_function_parentheses = False
+
 # -- Intersphinx mapping
 
 intersphinx_mapping = {
@@ -55,8 +61,11 @@
 # -- API docs settings
 apidoc_module_dir = "../../python/differt"
 apidoc_output_dir = "reference"
+apidoc_excluded_paths = ["conftest.py"]
 apidoc_separate_modules = True
 apidoc_toc_file = False
+apidoc_module_first = True
+apidoc_extra_args = ["--maxdepth=1", "--template=source/_templates"]
 
 # -- OpenGraph settings
 

docs/source/index.rst

@@ -11,6 +11,6 @@ DiffeRT: Differentiable Ray Tracing Toolbox for Radio Propagation
 
 .. toctree::
    :maxdepth: 1
-   :caption: API
+   :caption: Reference
 
-   differt package<reference/differt>
+   Public API: differt package<reference/differt>