diff options
| author | zhangguanzhang <guanzhangzhang@gmail.com> | 2020-06-12 19:54:10 +0800 |
|---|---|---|
| committer | GitHub <noreply@github.com> | 2020-06-12 19:54:10 +0800 |
| commit | 64eae15aa7905dd49f4a348f6b4765dfb4d9dd91 (patch) | |
| tree | 2914c20a2e0e15383da50334cad89b9b85b209a1 /docs/Readme.md | |
| parent | 3218736cff4b718b8fe855759687cb66f19d6e1e (diff) | |
| parent | 8aa5cf3d45998bc92eaafd67ab2a59e3722bade4 (diff) | |
| download | podman-64eae15aa7905dd49f4a348f6b4765dfb4d9dd91.tar.gz podman-64eae15aa7905dd49f4a348f6b4765dfb4d9dd91.tar.bz2 podman-64eae15aa7905dd49f4a348f6b4765dfb4d9dd91.zip | |
Merge pull request #1 from containers/master
# sync
Diffstat (limited to 'docs/Readme.md')
| -rw-r--r-- | docs/Readme.md | 30 |
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: + + + +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. |