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