Increase the strictness of the tox environment for building documentation
#1587
Conversation
Codecov Report
@@ Coverage Diff @@
## main #1587 +/- ##
=======================================
Coverage 97.21% 97.21%
=======================================
Files 83 83
Lines 7961 7961
=======================================
Hits 7739 7739
Misses 222 222
Continue to review full report at Codecov.
|
|
Oh, good. Only 959 lines of warnings this time. 😐 (Fortunately, though, most of them are the same warning but just repeated.) |
namurphy
added
no changelog entry needed
docs
github-actions
bot
added
the
plasmapy.particles
These were causing warnings
github-actions
bot
added
plasmapy.formulary
For some reason it is not working in nitpicky doc builds, but I haven't been able to figure out why.
namurphy
changed the title
tox environment for building documentation
|
I think this is the first time I've gotten a nitpicky doc build to work without errors! 🥲 |
| :orphan: | ||
|
|
||
| `plasmapy.particles.particle_collections` | ||
| ========================================= | ||
|
|
||
| .. currentmodule:: plasmapy.particles.particle_collections | ||
|
|
||
| .. automodapi:: plasmapy.particles.particle_collections |
There was a problem hiding this comment.
This had only been missing for approximately 4.2 × 107 seconds!
| @@ -59,7 +59,7 @@ Deprecations and Removals | |||
| `~plasmapy.particles.ionization_state.IonizationState.charge_numbers`. (`#1136 <https://github.com/plasmapy/plasmapy/pull/1136>`__) | |||
There was a problem hiding this comment.
For a future thought... Do we want to keep this CHANGELOG.rst? It feels like we're just duplicating the information. To me it makes more sense to remove this file and rename docs/whatsnew -> docs/changelog, and only have the changelog in one location. The only reason I see to keep CHANGELOG.rst is if towncrier forces us to keep it.
There was a problem hiding this comment.
Good point! I'm wondering about having the separate whatsnew pages for each of the releases, and then having a main changelog page that doesn't duplicate the information, but rather does a .. include:: directive for each of the whatsnew pages. I find it useful to have a full changelog page as well as the separate whatsnew pages (which we can link to in release announcements), though we have a couple of options that would work well. In any case, we'll gain some experience with towncrier in the next few days.
There was a problem hiding this comment.
I've used .. include:: in the past, but I've been moving away from it because is presents a potential security hole. I don't think it's a big deal in our usage, but still...
There was a problem hiding this comment.
Yep, it's best to avoid potential security holes even if it doesn't seem like it'll affect us. I'll link to this comment in #1595 as a post-release thing to think about or create an issue on.
changelog/1531.trivial.rst
Outdated
| Reduced execution time by avoiding calculations with units while keeping | ||
| unit validation. Added :file:`plasmapy/utils/units_definitions.py` to | ||
| precompute units. |
There was a problem hiding this comment.
This entry does not make sense on it's own. There is no context. Reduced execution timing of what? What is units_definitions.py? Also, this seems like two separate changelog entries.
changelog/1587.doc.rst
Outdated
| Increased the strictness of the ``build_docs`` tox_ environment so that | ||
| broken reST_ links now emit warnings which are then treated as errors, | ||
| removed the ``build_docs_nitpicky`` tox_ environment, and updated the | ||
| |documentation guide| accordingly. |
There was a problem hiding this comment.
Possibly add something about fixing all links that were failing under nitpicky. This could be added to this entry or as its own.
Prior to this pull request, our documentation builds would pass when there were typos like
plsmapy.formulary. Because of this, we ended up with a bunch of broken reST links that built up over time. I ended up doing some large PRs to fix these (e.g., #1207, #1257, and #1509).This PR enables the
-noption forsphinx-buildin thebuild_docsenvironment fortox. This will cause warnings to be emitted when there are broken reST links. The-Wflag (which was already present) made it so that the build would fail in case of any warnings. Having the-noption enabled will prevent the situation where broken reST links get passed through silently.This is a follow-up on #1206.