DOC: add logos and source button links (#311)

* DOC: link to APIs in doctests with sphinx-codeautolink

docs/conf.py

@@ -1,7 +1,8 @@
 from __future__ import annotations
 
-from sphinx_api_relink.helpers import get_package_version
+from sphinx_api_relink.helpers import get_branch_name, get_package_version
 
+BRANCH = get_branch_name()
 ORGANIZATION = "ComPWA"
 REPO_NAME = "policy"
 REPO_TITLE = "ComPWA repository policy"
@@ -32,19 +33,21 @@
 autodoc_member_order = "bysource"
 autodoc_typehints_format = "short"
 autosectionlabel_prefix_document = True
+codeautolink_concat_default = True
 copybutton_prompt_is_regexp = True
 copybutton_prompt_text = r">>> |\.\.\. "  # doctest
 copyright = "2023, Common Partial Wave Analysis"  # noqa: A001
 default_role = "py:obj"
 extensions = [
     "myst_parser",
+    "sphinx_api_relink",
+    "sphinx_codeautolink",
+    "sphinx_copybutton",
     "sphinx.ext.autodoc",
     "sphinx.ext.autosectionlabel",
     "sphinx.ext.doctest",
     "sphinx.ext.intersphinx",
     "sphinx.ext.napoleon",
-    "sphinx_api_relink",
-    "sphinx_copybutton",
     "sphinxarg.ext",
 ]
 generate_apidoc_package_path = f"../src/{PACKAGE_NAME}"
@@ -61,13 +64,30 @@
 html_static_path = ["_static"]
 html_theme = "sphinx_book_theme"
 html_theme_options = {
+    "icon_links": [
+        {
+            "name": "Common Partial Wave Analysis",
+            "url": "https://compwa.github.io",
+            "icon": "_static/favicon.ico",
+            "type": "local",
+        },
+        {
+            "name": "GitHub",
+            "url": f"https://github.com/{ORGANIZATION}/{REPO_NAME}",
+            "icon": "fa-brands fa-github",
+        },
+    ],
     "logo": {"text": "ComPWA policy"},
-    "repository_url": f"https://github.com/{ORGANIZATION}/{REPO_NAME}",
-    "repository_branch": "main",
     "path_to_docs": "docs",
-    "use_repository_button": True,
+    "repository_branch": BRANCH,
+    "repository_url": f"https://github.com/{ORGANIZATION}/{REPO_NAME}",
     "show_navbar_depth": 2,
     "show_toc_level": 2,
+    "use_download_button": False,
+    "use_edit_page_button": True,
+    "use_issues_button": True,
+    "use_repository_button": True,
+    "use_source_button": True,
 }
 html_title = REPO_TITLE
 intersphinx_mapping = {

pyproject.toml

@@ -57,6 +57,7 @@ doc = [
     "sphinx-api-relink",
     "sphinx-argparse",
     "sphinx-book-theme",
+    "sphinx-codeautolink",
     "sphinx-copybutton",
 ]
 sty = [

src/compwa_policy/utilities/vscode.py

@@ -178,7 +178,8 @@ def sort_case_insensitive(dct):  # type: ignore[no-untyped-def]
     sorting that is the same as `the one used by VS Code
     <https://code.visualstudio.com/updates/v1_76#_jsonc-document-sorting>`_.
 
-    >>> import pytest, sys
+    >>> import sys
+    >>> import pytest
     >>> if sys.version_info >= (3, 12):
     ...     pytest.skip()
     >>> sort_case_insensitive({