-
Notifications
You must be signed in to change notification settings - Fork 140
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Fix ReadTheDocs build #321
Conversation
This fixes the current build failure.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I love it :) Thanks.
Only minor comments.
Feel free to address them as you wish and merge without another round of review.
version: 2 | ||
|
||
sphinx: | ||
fail_on_warning: false |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I agree, if only I could figure out how to fix that warning.
|
||
formats: | ||
- epub |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Is epub used?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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 <[email protected]>
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. |
docs
extraI've also enabled PR builds in the ReadTheDocs configuration, so the build status should be reported here.
Closes #296.