github.com/containers/podman/v2@v2.2.2-0.20210501105131-c1e07d070c4c/docs/Readme.md (about)

     1  # Podman Documentation
     2  
     3  The online man pages and other documents regarding Podman can be found at
     4  [Read The Docs](https://podman.readthedocs.io).  The man pages
     5  can be found under the [Commands](https://podman.readthedocs.io/en/latest/Commands.html)
     6  link on that page.
     7  
     8  # Build the Docs
     9  
    10  ## Directory Structure
    11  
    12  |                                      | Directory                   |
    13  | ------------------------------------ | --------------------------- |
    14  | Markdown source for man pages        | docs/source/markdown/       |
    15  | man pages aliases as .so files       | docs/source/markdown/links/ |
    16  | restructured text for readthedocs.io | docs/rst/                   |
    17  | target for output                    | docs/build                  |
    18  | man pages                            | docs/build/man              |
    19  | remote linux man pages               | docs/build/remote/linux     |
    20  | remote darwin man pages              | docs/build/remote/darwin    |
    21  | remote windows html pages            | docs/build/remote/windows   |
    22  
    23  ## Support files
    24  
    25  | | |
    26  | ------------------------------------ | --------------------------- |
    27  | docs/remote-docs.sh | Read the docs/source/markdown files and format for each platform |
    28  | docs/links-to-html.lua | pandoc filter to do aliases for html files |
    29  
    30  ## API Reference
    31  
    32  The [latest online documentation](http://docs.podman.io/en/latest/_static/api.html) is
    33  automatically generated by two cooperating automation systems based on committed upstream
    34  source code.  Firstly, [the Cirrus-CI docs task](../contrib/cirrus/README.md#docs-task) builds
    35  `pkg/api/swagger.yaml` and uploads it to a public-facing location (Google Storage Bucket -
    36  an online service for storing unstructured data).  Second, [Read The Docs](readthedocs.com)
    37  reacts to the github.com repository change, building the content for the [libpod documentation
    38  site](https://podman.readthedocs.io/).  This site includes for the API section,
    39  some javascript which consumes the uploaded `swagger.yaml` file directly from the Google
    40  Storage Bucket.
    41  
    42  Since there are multiple systems and local cache is involved, it's possible that updates to
    43  documentation (especially the swagger/API docs) will lag by 10-or-so minutes.  However,
    44  because the client (i.e. your web browser) is fetching content from multiple locations that
    45  do not share a common domain, accessing the API section may show a stack-trace similar to
    46  the following:
    47  
    48  ![Javascript Stack Trace Image](../contrib/cirrus/swagger_stack_trace.png)
    49  
    50  If reloading the page, or clearing your local cache does not fix the problem, it is
    51  likely caused by broken metadata needed to protect clients from cross-site-scripting
    52  style attacks.  Please [notify a maintainer](https://github.com/containers/podman#communications)
    53  so they may investigate how/why the `swagger.yaml` file's CORS-metadata is
    54  incorrect, or the file isn't accessible for some other reason.