From e2573b734efa17c476afac54a98c50aac62cb5c6 Mon Sep 17 00:00:00 2001 From: Ed Santiago Date: Thu, 15 Sep 2022 13:49:03 -0600 Subject: Fix broken titles on readthedocs 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, format. Also update local-testing documentation in README, and clean it up a little. Fixes: #15822 Signed-off-by: Ed Santiago --- docs/README.md | 15 +++++++++++---- 1 file changed, 11 insertions(+), 4 deletions(-) (limited to 'docs/README.md') diff --git a/docs/README.md b/docs/README.md index 0f2af16d6..abe7d7758 100644 --- a/docs/README.md +++ b/docs/README.md @@ -13,7 +13,6 @@ link on that page. | ------------------------------------ | --------------------------- | | Markdown source for man pages | docs/source/markdown/ | | man pages aliases as .so files | docs/source/markdown/links/ | -| restructured text for readthedocs.io | docs/rst/ | | target for output | docs/build | | man pages | docs/build/man | | remote linux man pages | docs/build/remote/linux | @@ -60,16 +59,24 @@ incorrect, or the file isn't accessible for some other reason. ## Local Testing -Assuming that you have the [dependencies](https://podman.io/getting-started/installation#build-and-run-dependencies) +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): ``` -# dnf install python3-sphinx python3-recommonmark -# pip install sphinx-markdown-tables +$ 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/` -- cgit v1.2.3-54-g00ecf