From f3b41dbfea8c4e3d2049fe363c11115f1b9e6d14 Mon Sep 17 00:00:00 2001
From: Rohan McGovern <rmcgover@redhat.com>
Date: Fri, 12 Apr 2024 09:54:10 +1000
Subject: [PATCH] docs: allow for customization of the application's main doc
 string

The built-in docs are worded in a generic way; e.g. since authentication
is beyond the scope of exodus-gw itself, the doc string under that
section vaguely suggests to consult "internal documentation".

Internal users need a way to actually find the docs relevant to them, so
let's allow these sections to be customized. Let the doc strings use env
var substitution. This means we can set an environment variable to link
to proper internal docs about authentication, or to explain that the
specific deployed environments are "pre" and "live", etc.
---
 exodus_gw/docs.py | 43 +++++++++++++++++++++++++++++++++++++++++++
 exodus_gw/main.py | 32 ++++++--------------------------
 2 files changed, 49 insertions(+), 26 deletions(-)
 create mode 100644 exodus_gw/docs.py

diff --git a/exodus_gw/docs.py b/exodus_gw/docs.py
new file mode 100644
index 00000000..ec5d50d8
--- /dev/null
+++ b/exodus_gw/docs.py
@@ -0,0 +1,43 @@
+import os
+
+DEFAULT_OVERVIEW = ""
+
+DEFAULT_AUTHENTICATION = """
+The exodus-gw API does not include any direct support for authentication and is
+instead expected to be deployed behind a reverse-proxy implementing any desired
+authentication mechanism.
+
+If you are deploying an instance of exodus-gw, see
+[the deployment guide](https://release-engineering.github.io/exodus-gw/deployment.html)
+for information on how to integrate an authentication mechanism.
+
+If you are a client looking to make use of exodus-gw, consult your organization's
+internal documentation for advice on how to authenticate with exodus-gw.
+"""
+
+DEFAULT_ENVIRONMENTS = """
+The set of environments is configured when exodus-gw is deployed.
+A typical scenario is to deploy a "pre" environment for pre-release content and a
+"live" environment for live content.
+
+Different environments will also require the user to hold different roles. For example,
+a client might be permitted only to write to one of the configured environments, or all
+of them, depending on the configuration of the server.
+
+If you are deploying an instance of exodus-gw, see
+[the deployment guide](https://release-engineering.github.io/exodus-gw/deployment.html)
+for information on how to configure environments.
+
+If you are a client looking to make use of exodus-gw, consult your organization's
+internal documentation for advice on which environment(s) you should be using.
+"""
+
+
+def format(docstring: str) -> str:
+    return docstring.format(
+        OVERVIEW=os.getenv("EXODUS_GW_DOCS_OVERVIEW") or DEFAULT_OVERVIEW,
+        AUTHENTICATION=os.getenv("EXODUS_GW_DOCS_AUTHENTICATION")
+        or DEFAULT_AUTHENTICATION,
+        ENVIRONMENTS=os.getenv("EXODUS_GW_DOCS_ENVIRONMENTS")
+        or DEFAULT_ENVIRONMENTS,
+    )
diff --git a/exodus_gw/main.py b/exodus_gw/main.py
index 834bd3b6..e6f4a49a 100644
--- a/exodus_gw/main.py
+++ b/exodus_gw/main.py
@@ -1,5 +1,7 @@
 """The exodus-gw service provides APIs for uploading and publishing content on the exodus CDN.
 
+{OVERVIEW}
+
 Available APIs are grouped into the following categories:
 
 - [service](#tag/service): inspect the state of the exodus-gw service.
@@ -25,37 +27,14 @@
 
 ## Authentication
 
-The exodus-gw API does not include any direct support for authentication and is
-instead expected to be deployed behind a reverse-proxy implementing any desired
-authentication mechanism.
-
-If you are deploying an instance of exodus-gw, see
-[the deployment guide](https://release-engineering.github.io/exodus-gw/deployment.html)
-for information on how to integrate an authentication mechanism.
-
-If you are a client looking to make use of exodus-gw, consult your organization's
-internal documentation for advice on how to authenticate with exodus-gw.
-
+{AUTHENTICATION}
 
 ## Environments
 
 Many APIs in exodus-gw use the concept of an "environment" to control the target system
 of an operation.
 
-The set of environments is configured when exodus-gw is deployed.
-A typical scenario is to deploy a "pre" environment for pre-release content and a
-"live" environment for live content.
-
-Different environments will also require the user to hold different roles. For example,
-a client might be permitted only to write to one of the configured environments, or all
-of them, depending on the configuration of the server.
-
-If you are deploying an instance of exodus-gw, see
-[the deployment guide](https://release-engineering.github.io/exodus-gw/deployment.html)
-for information on how to configure environments.
-
-If you are a client looking to make use of exodus-gw, consult your organization's
-internal documentation for advice on which environment(s) you should be using.
+{ENVIRONMENTS}
 """
 
 import logging
@@ -75,6 +54,7 @@
 from starlette.concurrency import run_in_threadpool
 from starlette.exceptions import HTTPException as StarletteHTTPException
 
+from . import docs
 from .auth import log_login
 from .aws.util import xml_response
 from .database import db_engine
@@ -85,7 +65,7 @@
 
 app = FastAPI(
     title="exodus-gw",
-    description=__doc__,
+    description=docs.format(__doc__),
     openapi_tags=[
         service.openapi_tag,
         upload.openapi_tag,