mkdocs: Improve API reference signatures formatting

This commit improves the API reference formatting of signatures by
adding the following options to the `mkdocstrings` plugin:

- `separate_signature`: Separate the signature from the description.
- `show_signature_annotations`: Show the signature annotations.
- `signature_crossrefs`: Show cross-references in the signature (this is
  added only to be prepared for the future, as this is an insiders only
  feature for now).

We also add `black` as a dependency to generate the docs because it is
used to format the signatures nicely.

Signed-off-by: Leandro Lucarella <[email protected]>

Author: llucax

cookiecutter/{{cookiecutter.github_repo_name}}/mkdocs.yml

@@ -108,10 +108,13 @@ plugins:
             docstring_section_style: spacy
             inherited_members: true
             merge_init_into_class: false
+            separate_signature: true
             show_category_heading: true
             show_root_heading: true
             show_root_members_full_path: true
+            show_signature_annotations: true
             show_source: true
+            signature_crossrefs: true
           import:
             # TODO(cookiecutter): You might want to add other external references here
             # See https://mkdocstrings.github.io/python/usage/#import for details

cookiecutter/{{cookiecutter.github_repo_name}}/pyproject.toml

@@ -69,6 +69,7 @@ dev-flake8 = [
 ]
 dev-formatting = ["black == 23.9.1", "isort == 5.12.0"]
 dev-mkdocs = [
+  "black == 23.9.1",
   "Markdown==3.4.4",
   "mike == 1.1.2",
   "mkdocs-gen-files == 0.5.0",

mkdocs.yml

@@ -104,10 +104,13 @@ plugins:
             docstring_section_style: spacy
             inherited_members: true
             merge_init_into_class: false
+            separate_signature: true
             show_category_heading: true
             show_root_heading: true
             show_root_members_full_path: true
+            show_signature_annotations: true
             show_source: true
+            signature_crossrefs: true
           import:
             - https://cookiecutter.readthedocs.io/en/stable/objects.inv
             - https://docs.python.org/3/objects.inv

pyproject.toml

@@ -75,6 +75,7 @@ dev-flake8 = [
 ]
 dev-formatting = ["black == 23.9.1", "isort == 5.12.0"]
 dev-mkdocs = [
+  "black == 23.9.1",
   "Markdown==3.4.4",
   "mike == 1.1.2",
   "mkdocs-gen-files == 0.5.0",

tests_golden/integration/test_cookiecutter_generation/actor/frequenz-actor-test/mkdocs.yml

@@ -108,10 +108,13 @@ plugins:
             docstring_section_style: spacy
             inherited_members: true
             merge_init_into_class: false
+            separate_signature: true
             show_category_heading: true
             show_root_heading: true
             show_root_members_full_path: true
+            show_signature_annotations: true
             show_source: true
+            signature_crossrefs: true
           import:
             # TODO(cookiecutter): You might want to add other external references here
             # See https://mkdocstrings.github.io/python/usage/#import for details

tests_golden/integration/test_cookiecutter_generation/actor/frequenz-actor-test/pyproject.toml

@@ -51,6 +51,7 @@ dev-flake8 = [
 ]
 dev-formatting = ["black == 23.9.1", "isort == 5.12.0"]
 dev-mkdocs = [
+  "black == 23.9.1",
   "Markdown==3.4.4",
   "mike == 1.1.2",
   "mkdocs-gen-files == 0.5.0",

tests_golden/integration/test_cookiecutter_generation/api/frequenz-api-test/mkdocs.yml

@@ -108,10 +108,13 @@ plugins:
             docstring_section_style: spacy
             inherited_members: true
             merge_init_into_class: false
+            separate_signature: true
             show_category_heading: true
             show_root_heading: true
             show_root_members_full_path: true
+            show_signature_annotations: true
             show_source: true
+            signature_crossrefs: true
           import:
             # TODO(cookiecutter): You might want to add other external references here
             # See https://mkdocstrings.github.io/python/usage/#import for details

tests_golden/integration/test_cookiecutter_generation/api/frequenz-api-test/pyproject.toml

@@ -49,6 +49,7 @@ dev-flake8 = [
 ]
 dev-formatting = ["black == 23.9.1", "isort == 5.12.0"]
 dev-mkdocs = [
+  "black == 23.9.1",
   "Markdown==3.4.4",
   "mike == 1.1.2",
   "mkdocs-gen-files == 0.5.0",

tests_golden/integration/test_cookiecutter_generation/app/frequenz-app-test/mkdocs.yml

@@ -108,10 +108,13 @@ plugins:
             docstring_section_style: spacy
             inherited_members: true
             merge_init_into_class: false
+            separate_signature: true
             show_category_heading: true
             show_root_heading: true
             show_root_members_full_path: true
+            show_signature_annotations: true
             show_source: true
+            signature_crossrefs: true
           import:
             # TODO(cookiecutter): You might want to add other external references here
             # See https://mkdocstrings.github.io/python/usage/#import for details

tests_golden/integration/test_cookiecutter_generation/app/frequenz-app-test/pyproject.toml

@@ -50,6 +50,7 @@ dev-flake8 = [
 ]
 dev-formatting = ["black == 23.9.1", "isort == 5.12.0"]
 dev-mkdocs = [
+  "black == 23.9.1",
   "Markdown==3.4.4",
   "mike == 1.1.2",
   "mkdocs-gen-files == 0.5.0",