summaryrefslogtreecommitdiff
path: root/docs
diff options
context:
space:
mode:
Diffstat (limited to 'docs')
-rw-r--r--docs/Readme.md30
1 files changed, 23 insertions, 7 deletions
diff --git a/docs/Readme.md b/docs/Readme.md
index 987a5b8e4..9d3b9d06f 100644
--- a/docs/Readme.md
+++ b/docs/Readme.md
@@ -30,10 +30,26 @@ link on that page.
## API Reference
The [latest online documentation](http://docs.podman.io/en/latest/_static/api.html) is
-automatically generated from committed upstream sources. There is a short-duration
-cache involved, in case old content or an error is returned, try clearing your browser
-cache or returning to the site after 10-30 minutes.
-
-***Maintainers Note***: Please refer to [the Cirrus-CI tasks
-documentation](../contrib/cirrus/README.md#docs-task) for
-important operational details.
+automatically generated by two cooperating automation systems based on committed upstream
+source code. Firstly, [the Cirrus-CI docs task](../contrib/cirrus/README.md#docs-task) builds
+`pkg/api/swagger.yaml` and uploads it to a public-facing location (Google Storage Bucket -
+an online service for storing unstructured data). Second, [Read The Docs](readthedocs.com)
+reacts to the github.com repository change, building the content for the [libpod documentation
+site](https://podman.readthedocs.io/). This site includes for the API section,
+some javascript which consumes the uploaded `swagger.yaml` file directly from the Google
+Storage Bucket.
+
+Since there are multiple systems and local cache is involved, it's possible that updates to
+documentation (especially the swagger/API docs) will lag by 10-or-so minutes. However,
+because the client (i.e. your web browser) is fetching content from multiple locations that
+do not share a common domain, accessing the API section may show a stack-trace similar to
+the following:
+
+![Javascript Stack Trace Image](../contrib/cirrus/swagger_stack_trace.png)
+
+If reloading the page, or clearing your local cache does not fix the problem, it is
+likely caused by broken metadata needed to protect clients from cross-site-scripting
+style attacks. Please [notify a maintainer](https://github.com/containers/libpod#communications)
+so they may investigate how/why the swagger.yaml file's CORS-metadata is incorrect. See
+[the Cirrus-CI tasks documentation](../contrib/cirrus/README.md#docs-task) for
+details regarding this situation.