Set up ReST substitutions for docs #1147
Conversation
Codecov Report
@@ Coverage Diff @@
## master #1147 +/- ##
=======================================
Coverage 96.98% 96.98%
=======================================
Files 71 71
Lines 7022 7022
=======================================
Hits 6810 6810
Misses 212 212
Continue to review full report at Codecov.
|
This commit only uses the ReST substitutions for a class within the docstrings for that class and the methods/attributes of that class.
github-actions
bot
added
the
plasmapy.particles
This commit only uses the ReST substitutions for a class within the docstrings for that class and the methods/attributes of that class.
|
|
Stuff I still need to do:
|
namurphy
changed the title
docs/common_links.txt
Outdated
| @@ -0,0 +1,60 @@ | |||
| .. These are ReST substitutions and links that can be used throughout the docs | |||
There was a problem hiding this comment.
I think this should be a .rst file and not a .txt file. It's already formatted as a RST file and my IDE is going mad with RST commands in a normal txt file.
There was a problem hiding this comment.
I just tried changing that and got an error that the substitution for CustomParticle is being defined twice. I think what's happening is that this is being treated as a source file now when it shouldn't be. A little less likely is that rst_epilog...which contains the contents of this file...is being appended to this file. I'm attempting to add this file name to exclude_patterns in conf.py...
Co-authored-by: Erik Everson <eteverson@gmail.com>
| |Particle| Class | ||
| **************** |
There was a problem hiding this comment.
I'm surprised substitutions in headings don't produce build warnings due to the length of underline being shorter than the heading after the substitution. I'm really curious what's going on behind the scenes here, but I'm going to resist going down the rabbit hole.
There was a problem hiding this comment.
Given my experience with rabbit holes, we should probably rename them into dragon holes.
| @@ -71,7 +72,7 @@ accessed using `~plasmapy.particles.standard_atomic_weight`. | |||
| <Quantity 207.2 u> | |||
There was a problem hiding this comment.
I can't directly comment on the line, but go up 3 lines from here and up the xref needs .atomic. added to it...
~plasmapy.particles.atomic.standard_atomic_weight
There was a problem hiding this comment.
Looks like there are a few others in that file. I'll learn my lesson and start a separate PR with a well-defined scope. Edited to add: #1158.
| .. _install-pip: | ||
|
|
||
| Installation with pip | ||
| --------------------- | ||
|
|
||
| To install the most recent release of PlasmaPy on `PyPI`_ | ||
| with `pip <https://pip.pypa.io/en/stable/>`_ into an existing Python environment | ||
| with `pip`_ into an existing Python environment |
There was a problem hiding this comment.
If we add pip to the intersphinx_mappings dict, then `pip` will likely automatically cross-reference.
Just a thought, I'm fine with it either way.
There was a problem hiding this comment.
I tried adding pip to intersphinx_mappings but the link didn't work, so I reverted the change rather than go down a dragon hole. I'd be okay with this change at some future time.
Co-authored-by: Erik Everson <eteverson@gmail.com>
This reverts commit bc31885.
This PR follows the example of Astropy in setting up substitutions in docs (see their
docs/common_links.txtanddocs/conf.pyfiles). Instead of having~plasmapy.particles.particle_class.Particle, we can use|Particle|.This PR adapts code from Astropy but we can do that since we have a copy of Astropy's license.