github.com/hanks177/podman/v4@v4.1.3-0.20220613032544-16d90015bc83/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  | docs/use-pagetitle.lua | pandoc filter to set html document title |
    30  
    31  ## Manpage Syntax
    32  
    33  The syntax for the formatting of all man pages can be found [here](MANPAGE_SYNTAX.md).
    34  
    35  ## API Reference
    36  
    37  The [latest online documentation](http://docs.podman.io/en/latest/_static/api.html) is
    38  automatically generated by two cooperating automation systems based on committed upstream
    39  source code.  Firstly, [the Cirrus-CI docs task](../contrib/cirrus/README.md#docs-task) builds
    40  `pkg/api/swagger.yaml` and uploads it to a public-facing location (Google Storage Bucket -
    41  an online service for storing unstructured data).  Second, [Read The Docs](readthedocs.com)
    42  reacts to the github.com repository change, building the content for the [libpod documentation
    43  site](https://podman.readthedocs.io/).  This site includes for the API section,
    44  some javascript which consumes the uploaded `swagger.yaml` file directly from the Google
    45  Storage Bucket.
    46  
    47  Since there are multiple systems and local cache is involved, it's possible that updates to
    48  documentation (especially the swagger/API docs) will lag by 10-or-so minutes.  However,
    49  because the client (i.e. your web browser) is fetching content from multiple locations that
    50  do not share a common domain, accessing the API section may show a stack-trace similar to
    51  the following:
    52  
    53  ![JavaScript Stack Trace Image](../contrib/cirrus/swagger_stack_trace.png)
    54  
    55  If reloading the page, or clearing your local cache does not fix the problem, it is
    56  likely caused by broken metadata needed to protect clients from cross-site-scripting
    57  style attacks.  Please [notify a maintainer](https://github.com/containers/podman#communications)
    58  so they may investigate how/why the `swagger.yaml` file's CORS-metadata is
    59  incorrect, or the file isn't accessible for some other reason.
    60  
    61  ## Local Testing
    62  
    63  Assuming that you have the [dependencies](https://podman.io/getting-started/installation#build-and-run-dependencies)
    64  installed, then also install (showing Fedora in the example):
    65  
    66  ```
    67  # dnf install python3-sphinx python3-recommonmark
    68  # pip install sphinx-markdown-tables
    69  ```
    70  After that completes, cd to the `docs` directory in your Podman sandbox and then do `make html`.
    71  
    72  You can then preview the html files in `docs/build/html` with:
    73  ```
    74  python -m http.server 8000 --directory build/html
    75  ```