diff options
| author | Ed Santiago <santiago@redhat.com> | 2022-09-15 13:49:03 -0600 |
|---|---|---|
| committer | Ed Santiago <santiago@redhat.com> | 2022-09-15 14:35:06 -0600 |
| commit | e2573b734efa17c476afac54a98c50aac62cb5c6 (patch) | |
| tree | 03a4a2772d1e1a82836c4467b0fde79da2bc8e4a /docs | |
| parent | 750726e62c13941a739ef70040a1ec0d745cdb43 (diff) | |
| download | podman-e2573b734efa17c476afac54a98c50aac62cb5c6.tar.gz podman-e2573b734efa17c476afac54a98c50aac62cb5c6.tar.bz2 podman-e2573b734efa17c476afac54a98c50aac62cb5c6.zip | |
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, <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>
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/README.md | 15 | ||||
| -rw-r--r-- | docs/source/conf.py | 4 |
2 files changed, 13 insertions, 6 deletions
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/` diff --git a/docs/source/conf.py b/docs/source/conf.py index b58bb3f46..345e289e1 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -86,12 +86,12 @@ def convert_markdown_title(app, docname, source): if docpath.endswith(".md"): # Convert pandoc title line into eval_rst block for myst_parser # - # Remove the ending "(1)" to avoid it from being displayed + # Remove the ending " 1" (section) to avoid it from being displayed # in the web tab. 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. - source[0] = re.sub(r"^% (.*)(\(\d\))", r"```{title} \g<1>\n```", source[0]) + source[0] = re.sub(r"^% (.*)\s(\d)", r"```{title} \g<1>\n```", source[0]) def setup(app): app.connect("source-read", convert_markdown_title) |