Fix readthedocs doc generation. #1081
Conversation
We haven't been updating rtd for a long time, since no one active on the project had permission to do so. We now do have that permission, so we should update the docs. - Add an rtd config file, instead of relying on updating config in the rtd web app. - A custom sphinx directive to generate documentation for the runtime env vars. - Remove the API reference, since we now make no guarantees about internal API stability, and expect users to invoke the CLI. - Format example console content using the `console` format instead of `bash`, since the content may include command output, which is not itself parseable as bash. - Fix a bug in the sphinx config file. - Fix bad rst (unlike in md, header underlines must extend at least as far as the text being underlined). - Format the docstrings in variables.py so they render nicely.
|
A followup change will migrate from optparse to argparse, as there is an existing sphinx plugin for generating docs from argparse flags, but there is no equivalent for optparse, and I don't feel like making one... |
|
Download and extract this archive, and then |
Argh, I moved it (per the comment) but isort moved it back. Will add |
|
It looks like there are still some issues building: https://readthedocs.org/projects/pex/builds/12135240/ |
|
Ugh this appears to be because it runs a really old version of sphinx (v1.8.5). If I rerun those steps in the same docker image I can reproduce, and if I pin the sphinx version to 3.2.0 (which is what |
|
Fixed (hopefully) in #1082 |
We haven't been updating rtd for a long time, since no one
active on the project had permission to do so. We now do have
that permission, so we should update the docs.
in the rtd web app.
runtime env vars.
internal API stability, and expect users to invoke the CLI.
consoleformat insteadof
bash, since the content may include command output, whichis not itself parseable as bash.
least as far as the text being underlined).