mirror of
https://github.com/containers/podman.git
synced 2026-07-26 15:07:01 -04:00
8136cfbe4d
I forgot to update the docs here when I reworked the build process. Link
to the new location and explain how users can download the file, see
https://github.com/podman-container-tools/podman/discussions/29035
Now because the file is served on the same domain there should also be
no longer any issue with CORS so remove the old picture.
Fixes: c2ffe88ce0 ("build the swagger.yml on readthedocs")
Signed-off-by: Paul Holzinger <pholzing@redhat.com>
70 lines
3.1 KiB
Markdown
70 lines
3.1 KiB
Markdown
# 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/`
|