Fix ReadTheDocs build #321
Conversation
This fixes the current build failure.
| version: 2 | ||
|
|
||
| sphinx: | ||
| fail_on_warning: false |
There was a problem hiding this comment.
This is ok. If you set it to True, RTD will report a failure if a warning is present, but will not generate the HTML.
I prefer to have the HTML on RTD even on warnings... so that you can check the result.
And have a separate GiHub action that will fail on errors.
I see there is an existing 'docs' jobs it's green even with one warning
/home/runner/work/treq/treq/docs/api.rst:80: WARNING: more than one target found for cross-reference 'request': treq.request, treq.client.HTTPClient.request, treq.testing.treq.testing.StubTreq.request, treq.testing.RequestTraversalAgent.request
There was a problem hiding this comment.
I agree, if only I could figure out how to fix that warning.
|
|
||
| formats: | ||
| - epub |
There was a problem hiding this comment.
It was enabled in the RTG GUI before, so I left it enabled.
|
|
||
| pip install treq[dev] | ||
| tox -e py38-twisted_latest |
There was a problem hiding this comment.
just a minor comment.... feel free to ignore as I might be wrong :)
It would be nice to name the tox test envs like py38-test-twisted_latest``. In this way, you can call tox -e test-twisted_latest` and it will run with your default python.
There was a problem hiding this comment.
Actually, you can do tox -e twisted_latest to run with your default Python as-is. The default commands are to test.
|
|
||
| Build docs:: | ||
|
|
||
| tox -e docs | ||
|
|
||
| To do it all:: | ||
|
|
||
| tox -p |
There was a problem hiding this comment.
On my tox version I need to explicitly specify all or a number of parallel builds
$ tox --version
3.13.2
| tox -p | |
| tox -p all |
There was a problem hiding this comment.
You should update your Tox. :) I don't need to pass anything on 3.20.1; it defaults to the number of CPU on my machine. all is semantically different: it runs all the jobs in parallel, regardless of available resources.
There was a problem hiding this comment.
you can set a minversion to avoid this: https://tox.readthedocs.io/en/latest/config.html#conf-minversion
| @@ -53,6 +51,7 @@ commands = | |||
| check-manifest | |||
|
|
|||
| [testenv:docs] | |||
| extras = docs | |||
| changedir = docs | |||
| commands = | |||
| sphinx-build -b html . html | |||
There was a problem hiding this comment.
My suggestion is fail on warnings. In this way the docs should be "clean".
| sphinx-build -b html . html | |
| sphinx-build -W --keep-going -b html . html |
There was a problem hiding this comment.
I 100% agree, but I've never been able to figure out how to clear the remaining warning. It has been a while since I looked at it, but IIRC it is implying a cross-reference from an ivar (which makes no sense, but I've seen similar issues on other projects).
Co-authored-by: Adi Roiban <adiroiban@gmail.com>
|
Thank you for the review @adiroiban! I filed #322 to follow up on the Sphinx warning. I'll go ahead and merge this once it greens up since doing so will fix the failing RTD check on another PR. |
docsextraI've also enabled PR builds in the ReadTheDocs configuration, so the build status should be reported here.
Closes #296.