It's spooky, but it looks like black moved this here.

Yeah, this is definitely a PEP8 thing. I had the same warnings on my IDE. I'm torn about this though...yes having it at the top satisfies PEP8, but having it where it was is more readable IMHO.

It might be best to just move the full release and version declaration here.

This had moved away from mathematics a while ago.

Why not just use the .. nbsphinx:: directive for this?

I tried and it started populating the TOC with these three examples.

If you happen to know a way to do a nbsphinx directive without the TOC entries, it'd be much appreciated!

Try :hidden

Turns out :hidden: shows its contents in the TOC and hides the display on the main page, see the screenshot:

There's an extra duplicated TOC in there that's not seen in the main page.

This could be an option...https://sphinx-rtd-theme.readthedocs.io/en/stable/configuring.html#confval-includehidden. This would prevent hidden toctree's from adding to the sidebar. The trade-off, we can no longer hide our toctree's in the main index page.

I think both ways have comparable PROs and CONs that make them equally nice and annoying. I'll leave the choice up to you.

Let's tinker with it another day, if that's all right with you. :) I'd love to apply a fix that doesn't propagate elsewhere to this, but I won't lose sleep over skipping it for now.

This becomes an interesting choice/dilemma. What do we do if we want ClassicalTransport to link back to the documentation for the class? I currently see three choices:

1. Don't link back to the class/function/package/etc. documentation?
2. Use markdown style linking, like [ClassicalTransport](../api/plasmapy.formulary.braginskii.ClassicalTransport.rst). However, this style of linking does not support code highlighting, e.g. [`ClassicalTransport`](...).
3. Mark the cell_type as raw with a restructuredtext metadata and then we could sill use the sphinx domains (i.e. :class:`~plasmapy.formulary.braginskii.ClassicalTransport` ). In this case the cell would look something like...

   "cell_type": "raw",
   "metadata": {"raw_minetype": "text/restructuredtext"},
   "source": [
    "They also change with direction with respect to the magnetic field. Here,\n",
    "we choose to print out, as arrays, the (parallel, perpendicular,\n",
    "and cross) directions. Take a look at the docs to \n"
    ":class:`~plasmapy.formulary.braginskii.ClassicalTransport`\n",
    "for more information on these.\n",
    "\n"
   ]

Personally, I like option 3 because it keeps the style consistent in all of the documentation, but it has issues too. It takes more effort (not much) to setup. I'm not sure how this would behave if there were more advanced roles involved. Also, it might render/look a little weird if someone were to download the notebook and use it outside the documentation environment.

There was an issue I found about it, lemme grab breakfast and I'll find it for you...

@rocco8773 here's the issue I had wanted to find for you:

spatialaudio/nbsphinx#308 (comment)

I'm trying to get this implemented here.

Ah, future issue, maybe.

Yeah, that's basically option 2. I'm fine with leaving this to another day, but we should at least open an issue about linking API in notebooks.

It would be nice to have a command like this in the tox build_docs environment as well. These options should also be mentioned in the documentation itself, probably in the Documentation Guidelines section.