Merge pull request #79 from python-discord/upgrade-docsv7.1.1

1 files changed, 80 insertions, 9 deletions

diff --git a/docs/conf.py b/docs/conf.py
index 8459f3fb..9aaa8eff 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -3,13 +3,18 @@
 
 import functools
 import os.path
+import shutil
 import sys
 from pathlib import Path
 
 import git
+import releases
+import sphinx.util.logging
 import tomli
 from sphinx.application import Sphinx
 
+logger = sphinx.util.logging.getLogger(__name__)
+
 # Handle the path not being set correctly in actions.
 sys.path.insert(0, os.path.abspath('..'))
 
@@ -21,10 +26,9 @@ project = "Bot Core"
 copyright = "2021, Python Discord"
 author = "Python Discord"
 
-PROJECT_ROOT = Path(__file__).parent.parent
 REPO_LINK = "https://github.com/python-discord/bot-core"
-SOURCE_FILE_LINK = f"{REPO_LINK}/blob/{git.Repo(PROJECT_ROOT).commit().hexsha}"
 
+PROJECT_ROOT = Path(__file__).parent.parent
 sys.path.insert(0, str(PROJECT_ROOT.absolute()))
 
 # The full version, including alpha/beta/rc tags
@@ -46,12 +50,14 @@ extensions = [
     "sphinx.ext.todo",
     "sphinx.ext.napoleon",
     "sphinx_autodoc_typehints",
+    "releases",
     "sphinx.ext.linkcode",
     "sphinx.ext.githubpages",
+    "sphinx_multiversion",
 ]
 
 # Add any paths that contain templates here, relative to this directory.
-templates_path = ["_templates"]
+templates_path = ["_templates", "pages"]
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
@@ -76,18 +82,24 @@ html_theme_options = {
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
 html_static_path = ["_static"]
+
+# Html files under pages/ are rendered separately and added to the final build
+html_additional_pages = {
+    file.removesuffix(".html"): file
+    for file in utils.get_recursive_file_uris(Path("pages"), "*.html")
+}
+
 html_title = f"{project} v{version}"
 html_short_title = project
 
 html_logo = "https://raw.githubusercontent.com/python-discord/branding/main/logos/logo_full/logo_full.min.svg"
 html_favicon = html_logo
 
-html_css_files = [
-    "index.css",
-    "logo.css",
-]
+static = Path("_static")
+html_css_files = utils.get_recursive_file_uris(static, "*.css")
+html_js_files = utils.get_recursive_file_uris(static, "*.js")
 
-utils.cleanup()
+utils.build_api_doc()
 
 
 def skip(*args) -> bool:
@@ -102,9 +114,32 @@ def skip(*args) -> bool:
     return would_skip
 
 
+def post_build(_: Sphinx, exception: Exception) -> None:
+    """Clean up and process files after the build has finished."""
+    if exception:
+        # Don't accidentally supress exceptions
+        raise exception from None
+
+    build_folder = PROJECT_ROOT / "docs" / "build"
+    main_build = build_folder / "main"
+
+    if main_build.exists() and not (build_folder / "index.html").exists():
+        # We don't have an index in the root folder, add a redirect
+        shutil.copy((main_build / "index_redirect.html"), (build_folder / "index.html"))
+        shutil.copytree((main_build / "_static"), (build_folder / "_static"), dirs_exist_ok=True)
+        (build_folder / ".nojekyll").touch(exist_ok=True)
+
+
 def setup(app: Sphinx) -> None:
     """Add extra hook-based autodoc configuration."""
     app.connect("autodoc-skip-member", skip)
+    app.connect("build-finished", post_build)
+    app.add_role("literal-url", utils.emphasized_url)
+
+    # Add a `breaking` role to the changelog
+    releases.ISSUE_TYPES["breaking"] = "F50F10"  # This is the hex for a light red color
+    releases.reorder_release_entries = utils.reorder_release_entries
+    app.add_role("breaking", releases.issues_role)
 
 
 ignored_modules = [
@@ -147,4 +182,40 @@ intersphinx_mapping = {
 
 
 # -- Options for the linkcode extension --------------------------------------
-linkcode_resolve = functools.partial(utils.linkcode_resolve, SOURCE_FILE_LINK)
+linkcode_resolve = functools.partial(utils.linkcode_resolve, REPO_LINK)
+
+
+# -- Options for releases extension ------------------------------------------
+releases_github_path = REPO_LINK.removeprefix("https://github.com/")
+releases_release_uri = f"{REPO_LINK}/releases/tag/v%s"
+
+
+def _releases_setup(app: Sphinx) -> dict:
+    """Wrap the default setup of releases to declare it as parallel-read safe."""
+    _original_releases_setup(app)
+    return {"parallel_read_safe": True}
+
+
+_original_releases_setup = releases.setup
+releases.setup = _releases_setup
+
+
+# -- Options for the multiversion extension ----------------------------------
+# Filter out older versions, and don't build branches other than main
+# unless `BUILD_DOCS_FOR_HEAD` env variable is True.
+smv_remote_whitelist = "origin"
+smv_latest_version = "main"
+
+smv_branch_whitelist = "main"
+if os.getenv("BUILD_DOCS_FOR_HEAD", "False").lower() == "true":
+    if not (branch := os.getenv("BRANCH_NAME")):
+        try:
+            branch = git.Repo(PROJECT_ROOT).active_branch.name
+        except git.InvalidGitRepositoryError:
+            pass
+
+    if branch:
+        logger.info(f"Adding branch {branch} to build whitelist.")
+        smv_branch_whitelist = f"main|{branch}"
+
+smv_tag_whitelist = r"v(?!([0-6]\.)|(7\.[0-1]\.0))"  # Don't include any versions prior to v7.1.1