diff --git a/docs/source/_templates/module.rst_t b/docs/source/_templates/module.rst_t new file mode 100644 index 00000000..825dd9dc --- /dev/null +++ b/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 %} diff --git a/docs/source/_templates/package.rst_t b/docs/source/_templates/package.rst_t new file mode 100644 index 00000000..3ce725d3 --- /dev/null +++ b/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 %} diff --git a/docs/source/conf.py b/docs/source/conf.py index f9d0fbd0..f1dcbd95 100644 --- a/docs/source/conf.py +++ b/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 diff --git a/docs/source/index.rst b/docs/source/index.rst index a983df5c..7b72ecc3 100644 --- a/docs/source/index.rst +++ b/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 + Public API: differt package diff --git a/docs/source/reference/.gitkeep b/docs/source/reference/.gitkeep deleted file mode 100644 index e69de29b..00000000