spiegel_podman/docs

Podman Documentation

The online man pages and other documents regarding Podman can be found at Read The Docs. The man pages can be found under the Commands 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.

API Reference

The latest online documentation 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 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.

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 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 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/