# Podman Documentation

The online man pages and other documents regarding Podman can be found at
[Read The Docs](https://podman.readthedocs.io).  The man pages
can be found under the [Commands](https://podman.readthedocs.io/en/latest/Commands.html)
link on that page.

# Build the Docs

## Directory Structure

|                                      | Directory                   |
| ------------------------------------ | --------------------------- |
| Markdown source for man pages        | docs/source/markdown/       |
| man pages aliases as .so files       | docs/source/markdown/links/ |
| target for output                    | docs/build                  |
| man pages                            | docs/build/man              |
| remote linux man pages               | docs/build/remote/linux     |
| remote darwin man pages              | docs/build/remote/darwin    |
| remote windows html pages            | docs/build/remote/windows   |

## Support files

| | |
| ------------------------------------ | --------------------------- |
| docs/remote-docs.sh | Read the docs/source/markdown files and format for each platform |
| docs/links-to-html.lua | pandoc filter to do aliases for html files |
| docs/use-pagetitle.lua | pandoc filter to set html document title |

## Manpage Syntax

The syntax for the formatting of all man pages can be found [here](MANPAGE_SYNTAX.md).

## API Reference

The [latest online documentation](https://docs.podman.io/en/latest/_static/api.html) is
automatically generated by the readthedocs build process. It uses redoc to render the
swagger.yml file, the swagger is build and injected as static resource in the readthedocs
build process, see the [`.readthedocs.yaml`](../.readthedocs.yaml) file.

The swagger file can be downloaded from `https://docs.podman.io/en/latest/_static/swagger.yaml`.
Note the latest link always contains the latest yaml from the main branch, if you like a specific
version replace `latest` with the version, i.e. for `v6.0.0` `https://docs.podman.io/en/v6.0.0/_static/swagger.yaml`.
Also this new process is only done since v5.8.4. Earlier swagger.yml files where
uploaded [here](https://storage.googleapis.com/libpod-master-releases).

## Local Testing

To build standard man pages, run `make docs`. Results will be in `docs/build/man`.

To build HTMLized man pages: Assuming that you have the
[dependencies](https://podman.io/getting-started/installation#build-and-run-dependencies)
installed, then also install (showing Fedora in the example):

```
$ sudo dnf install python3-sphinx python3-recommonmark
$ pip install sphinx-markdown-tables myst_parser
```
(The above dependencies are current as of 2022-09-15. If you experience problems,
please see [requirements.txt](requirements.txt) in this directory, it will almost
certainly be more up-to-date than this README.)

After that completes, cd to the `docs` directory in your Podman sandbox and then do `make html`.

You can then preview the html files in `docs/build/html` with:
```
python -m http.server 8000 --directory build/html
```
...and point your web browser at `http://localhost:8000/`