Update tox configuration for building docs #1206
Merged
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Codecov Report
@@ Coverage Diff @@
## main #1206 +/- ##
=======================================
Coverage ? 96.99%
=======================================
Files ? 71
Lines ? 7050
Branches ? 0
=======================================
Hits ? 6838
Misses ? 212
Partials ? 0 Continue to review full report at Codecov.
|
|
Building the docs in nitpicky mode: build finished with problems, 1466 warnings.Huh. |
This was referenced Jul 23, 2021
StanczakDominik
approved these changes
Jul 27, 2021
tox.ini
Outdated
| @@ -41,14 +41,21 @@ changedir = {toxinidir} | |||
| extras = docs | |||
| setenv = | |||
| HOME = {envtmpdir} | |||
| commands = sphinx-build docs docs{/}_build{/}html -W -b html | |||
| commands = sphinx-build docs docs{/}_build{/}html -W --keep-going -j=auto -b html | |||
There was a problem hiding this comment.
Suggested change
| commands = sphinx-build docs docs{/}_build{/}html -W --keep-going -j=auto -b html | |
| commands = sphinx-build docs docs{/}_build{/}html -W --keep-going -b html {posargs} |
There was a problem hiding this comment.
tox -- -j=auto in github action workflow
|
From today's meeting...
|
StanczakDominik
approved these changes
Jul 28, 2021
Comment on lines
+132
to
+136
| When writing documentation, please make sure to fix any warnings that | ||
| arise. To enforce this, the ``build_docs`` and ``build_docs_nitpicky`` | ||
| tox_ environments will fail after completing the documentation build | ||
| if they encountered any warnings (via the ``-W`` and ``--keep-going`` | ||
| flags to `sphinx-build`_). |
There was a problem hiding this comment.
Would you like to add a github action for nitpicky?
There was a problem hiding this comment.
Not yet, but I would really like to once all of the ∼10³ nitpicky warnings → errors are resolved. That's going to take some time and might also depend on #1158 (and/or maybe #1149?) to be resolved to define what optional, etc. mean in the parameters section of docstrings. Eventually a GitHub Action for nitpicky would be great!
rocco8773
reviewed
Aug 10, 2021
rocco8773
reviewed
Aug 10, 2021
Co-authored-by: Erik Everson <[email protected]>
… tox-docs-nitpicky
rocco8773
approved these changes
Aug 10, 2021
|
pre-commit.ci autofix |
for more information, see https://pre-commit.ci
Tlord18
pushed a commit
to Tlord18/PlasmaPy
that referenced
this pull request
Oct 6, 2021
* Add build_docs_nitpicky test thing to tox.ini * Continue doc build after a warning when using -W option * Add --parallel=auto flag to doc builds with tox * Fix parallel argument to sphinx-build for tox * Fix order of options * Add changelog entry for tox docs env updates * Update doc guide on tox environments * Add changelog entry for updating doc guide regarding tox envs * Update doc guide section on tox docs builds * Fix reST link * Remove auto parallelization for doc builds via tox * Separate changelog entries * Further details on the -j flag for parallelization in doc builds Co-authored-by: Erik Everson <[email protected]> * Separate changelog entries * [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci Co-authored-by: Erik Everson <[email protected]> Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Tlord18
pushed a commit
to Tlord18/PlasmaPy
that referenced
this pull request
Oct 6, 2021
* Add build_docs_nitpicky test thing to tox.ini * Continue doc build after a warning when using -W option * Add --parallel=auto flag to doc builds with tox * Fix parallel argument to sphinx-build for tox * Fix order of options * Add changelog entry for tox docs env updates * Update doc guide on tox environments * Add changelog entry for updating doc guide regarding tox envs * Update doc guide section on tox docs builds * Fix reST link * Remove auto parallelization for doc builds via tox * Separate changelog entries * Further details on the -j flag for parallelization in doc builds Co-authored-by: Erik Everson <[email protected]> * Separate changelog entries * [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci Co-authored-by: Erik Everson <[email protected]> Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
This makes/proposes a few changes:
build_docs_nitpicky, that issues warnings for missing links.--keep-goingflag when we have the-Wflag. This way the test doc build will keep going after a warning, which will let us fix multiple warnings at the same time instead of having to wait for the doc build run multiple times.--parallel=auto. This is experimental, and does notmake the change in GitHub Actionsalter our GitHub Actions setup, so as far as I can tell, the doc builds there will still only be done on one core rather than in parallel. (edited as a clarification)