-
Notifications
You must be signed in to change notification settings - Fork 10
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
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.
- Loading branch information
Showing
2 changed files
with
49 additions
and
26 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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_docs(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, | ||
) |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters