Tell sphinx not to process the "options" dir, those files
are not to be published.
Context: websearching for podman volume info, I stumbled upon:
https://docs.podman.io/en/latest/markdown/options/volume.html
...and panicked because I saw '<<container|pod>>', the options
include-file syntax that should never be seen by users. I thought
the filter script was broken.
Signed-off-by: Ed Santiago <santiago@redhat.com>
Followup to #15621, which (correctly) removed parentheses from
md files. Turns out, a hidden part of our readthedocs process
depended on those parentheses. Update that step so it handles
the new, correct, <space><section-number> format.
Also update local-testing documentation in README, and clean it
up a little.
Fixes: #15822
Signed-off-by: Ed Santiago <santiago@redhat.com>
When docs.podman.io is build on readthedocs we have to make sure to
generate the markdown pages first.
It works locally with sphinx but I have no idea if this works on the
readthedocs infra.
Signed-off-by: Paul Holzinger <pholzing@redhat.com>
* Remove the ending text "(1)" to avoid it from being
displayed in the web tab title for a command man page
on the web. Often such a text indicates that a web
page got an update. For instance GitHub issues shows
the number of new comments that have been written
after the user's last visit.
Fixes#13438
Signed-off-by: Erik Sjölund <erik.sjolund@gmail.com>
Recommonmark has many issues and is deprecated. The recommended
alternative is MyST-Parser. [1]
The myst parser looks great, it also correctly parses tables and adds the
correct links.
To test locallay run:
```
cd docs
rm -rf build/
\# install build deps
sudo dnf install python3-sphinx && pip install myst-parser
make html
python -m http.server 8000 --directory build/html
\# Now check in your browser if it looks good to you
```
[1] https://github.com/readthedocs/recommonmark/issues/221
Signed-off-by: Paul Holzinger <pholzing@redhat.com>
Developers asked for a deterministic field to verify if podman is
running via API or linked directly to libpod library.
$ podman info --format '{{.Host.ServiceIsRemote}}'
false
$ podman-remote info --format '{{.Host.ServiceIsRemote}}'
true
$ podman --remote info --format '{{.Host.ServiceIsRemote}}'
true
* docs/conf.py formatted via black
Signed-off-by: Jhon Honce <jhonce@redhat.com>
In the documentation source `--` is only used in long option names or
console output. Currently any unescaped `--` that's not in a code
block/inline gets converted into a single "en dash". This is confusing
to the reader because long options start with two dashes, not one.
This switches off the dash transformation in Sphinx. Quotation marks,
apostrophes and ellipses are still transformed as before.
It also switches off all smart transforms in the podman-remote windows
documentation build. This matches the Linux man page build, which
doesn't use smart transforms.
Signed-off-by: Rob Cowsill <42620235+rcowsill@users.noreply.github.com>
When building Sphinx HTML docs, preprocess markdown files and convert
pandoc-style title lines into recommonmark eval_rst blocks
This gives command HTML pages the same title as the equivalent manpage
Fixes: containers/podman.io#385
Signed-off-by: Rob Cowsill <42620235+rcowsill@users.noreply.github.com>
Escape the two dashes, otherwise they are combined into one long dash.
I tested that this change is safe and still renders correctly on github
and with the man pages.
This commit also contains a small change to make it build locally.
Assuming you have the dependencies installed you can do:
```
cd docs
make html
```
Preview the html files in docs/build/html with
`python -m http.server 8000 --directory build/html`.
Fixescontainers/podman.io#373
Signed-off-by: Paul Holzinger <paul.holzinger@web.de>
Sphinx with recommonmark cannot render markdown tables at all.
There is a python package called `sphinx-markdown-tables` which
adds the markdown table support to recommonmark.
https://pypi.org/project/sphinx-markdown-tables/
By utilising this package we don't have to change our doc format.
Signed-off-by: Paul Holzinger <paul.holzinger@web.de>
Change the docs markdown so that flag names will be h4 headers.
Sphinx will automatically add anchors to headers. Add css to
make sure the flag names are not to big compared to the text.
The man pages also still renders fine but it looks a bit different.
Signed-off-by: Paul Holzinger <paul.holzinger@web.de>
Restructuring the docs dir to make integration with sphinx easier. man
pages now exist in docs/source/man and the sphinx make files exists in
docs.
Signed-off-by: baude <bbaude@redhat.com>
