From c7b9e6cf50513b39a4389e4b024a3d42285570f1 Mon Sep 17 00:00:00 2001
From: Remco de Boer <29308176+redeboer@users.noreply.github.com>
Date: Tue, 5 Dec 2023 10:01:18 +0100
Subject: [PATCH] MAINT: clean up Sphinx configuration (#239)

* MAINT: set logo directly with external link
* MAINT: use helper functions from `sphinx-api-relink`
---
 docs/conf.py | 73 +++++++---------------------------------------------
 setup.cfg    |  3 ++-
 2 files changed, 11 insertions(+), 65 deletions(-)

diff --git a/docs/conf.py b/docs/conf.py
index ebd7e0e1..cce5f45d 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -4,74 +4,15 @@
 documentation: https://www.sphinx-doc.org/en/master/usage/configuration.html
 """
 
-import contextlib
-import os
-import shutil
-import subprocess
-import sys
-from typing import Optional
-
-import requests
-
-if sys.version_info < (3, 8):
-    from importlib_metadata import version as get_package_version
-else:
-    from importlib.metadata import version as get_package_version
-
-
-def fetch_logo(url: str, output_path: str) -> None:
-    if os.path.exists(output_path):
-        return
-    online_content = requests.get(url, allow_redirects=True, timeout=10)
-    with open(output_path, "wb") as stream:
-        stream.write(online_content.content)
-
-
-def generate_api(package: str) -> None:
-    shutil.rmtree("api", ignore_errors=True)
-    subprocess.call(
-        " ".join(
-            [
-                "sphinx-apidoc",
-                f"../src/{package}/",
-                f"../src/{package}/version.py",
-                "-o api/",
-                "--force",
-                "--no-toc",
-                "--templatedir _templates",
-                "--separate",
-            ]
-        ),
-        shell=True,  # noqa: S602
-    )
-
-
-def get_html_logo_path() -> Optional[str]:
-    logo_path = "_static/logo.svg"
-    os.makedirs(os.path.dirname(logo_path), exist_ok=True)
-    with contextlib.suppress(requests.exceptions.ConnectionError):
-        fetch_logo(
-            url="https://raw.githubusercontent.com/ComPWA/ComPWA/04e5199/doc/images/logo.svg",
-            output_path=logo_path,
-        )
-    if os.path.exists(logo_path):
-        return logo_path
-    return None
-
-
-def get_version(package_name: str) -> str:
-    v = get_package_version(package_name)
-    return ".".join(v.split(".")[:3])
-
+from sphinx_api_relink.helpers import get_package_version
 
 REPO_NAME = "repo-maintenance"
 PACKAGE_NAME = "repoma"
-generate_api(PACKAGE_NAME)
 
 author = "Common Partial Wave Analysis"
 autodoc_member_order = "bysource"
-autosectionlabel_prefix_document = True
 autodoc_typehints_format = "short"
+autosectionlabel_prefix_document = True
 copybutton_prompt_is_regexp = True
 copybutton_prompt_text = r">>> |\.\.\. "  # doctest
 copyright = "2023, Common Partial Wave Analysis"  # noqa: A001
@@ -84,13 +25,17 @@ def get_version(package_name: str) -> str:
     "sphinx.ext.intersphinx",
     "sphinx.ext.napoleon",
     "sphinx.ext.viewcode",
+    "sphinx_api_relink",
     "sphinx_copybutton",
     "sphinxarg.ext",
 ]
+generate_apidoc_package_path = f"../src/{PACKAGE_NAME}"
 html_copy_source = True  # needed for download notebook button
 html_favicon = "_static/favicon.ico"
 html_last_updated_fmt = "%-d %B %Y"
-html_logo = get_html_logo_path()
+html_logo = (
+    "https://raw.githubusercontent.com/ComPWA/ComPWA/04e5199/doc/images/logo.svg"
+)
 html_show_copyright = False
 html_show_sourcelink = False
 html_show_sphinx = False
@@ -126,5 +71,5 @@ def get_version(package_name: str) -> str:
 nitpicky = True
 primary_domain = "py"
 project = REPO_NAME
-release = get_version(REPO_NAME)
-version = get_version(REPO_NAME)
+release = get_package_version(REPO_NAME)
+version = get_package_version(REPO_NAME)
diff --git a/setup.cfg b/setup.cfg
index ed17db90..e4b51bb7 100644
--- a/setup.cfg
+++ b/setup.cfg
@@ -54,6 +54,7 @@ doc =
     sphinx-argparse
     sphinx-book-theme
     sphinx-copybutton
+    sphinx-api-relink >=0.0.3
 test =
     pytest
     pytest-cov
@@ -62,8 +63,8 @@ format =
     black
 mypy =
     mypy
+    sphinx-api-relink >=0.0.3
     types-PyYAML
-    types-requests
     types-setuptools
     types-toml
 lint =