Plasmapy: Look into linking API docs from ipynb examples

[StanczakDominik]

1. Head back to https://github.com/PlasmaPy/PlasmaPy/pull/792#discussion_r426981656_ by @rocco8773
2. Try out the linked method of linking API docs
3. Modify a few of the notebooks so that the links work

[chttrjeankr]

Had a look at the discussion. Option 2 looks like it should work.

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`](...).

I tried it out on an example .ipynb file and code highlighting were supported. (Obviously, the links don't work in my example scenario)

Non-executed markdown cells contain the markdown needed for the executed cells below them.

Isn't this what we're looking for? Or am I missing something @rocco8773?

[chttrjeankr]

And a trial with the whole sentence in question.

[StanczakDominik]

The highlighting does look good; getting the links working reasonably well would be the main problem here, though.

[chttrjeankr]

getting the links working reasonably well would be the main problem

Due to the format of the links you mean? (../api/plasmapy.formulary.braginskii.ClassicalTransport.rst)

[rocco8773]

@chttrjeankr I do think the easiest option to implement is option 2. However, when I tried building the documentation with [`Somthing`](my link) the code highlighting didn't work. It's possible I did something wrong in my quick test, or there's an incompatibility with sphinx. If it does work, I don't see a big reason not to implement links this way.

I only have the personal gripe that the code syntax highlighting for markdown is different than that for restructuredText. This might be "easily" solved with a custom CSS though.

I do like the consistency with option 3, but it's more involved to setup and might cause issues if someone downloads the notebook to play with.

Would you be interested in opening a PR on this for us?

[StanczakDominik]

getting the links working reasonably well would be the main problem

Due to the format of the links you mean? (../api/plasmapy.formulary.braginskii.ClassicalTransport.rst)

Yeah, what I want to make sure here is that the links actually can be followed to what they're supposed to link to! :)

[rocco8773]

@StanczakDominik That would be a really nice feature (that the links still work if someone downloads the notebook). I'm not sure that would be the case with either option though.

For it to behave the like that, I think you'd have to use the full address (i.e. http://docs.plasmapy.org/en/latest/...). However, that would be annoying for local documentation builds since the links would always point to read the docs opposed to your locally generated files.

[StanczakDominik]

I wouldn't expect it to work from jupyter; I'd like to make sure it works with a local doc build, though. If that works, I'm like 90% sure it'll work on readthedocs.

[chttrjeankr]

or there's an incompatibility with sphinx.

@rocco8773 I believe this may be the case.

and might cause issues if someone downloads the notebook to play with.

I did the exact same thing to try it out and the notebooks failed to even load when I tried out the solution in the discussion.

Would you be interested in opening a PR on this for us?

Yup. I _want_ to, but feel a bit unfamiliar to sphinx. Although, it's nothing I can't do with some guidance from you if I face a snag.

For it to behave the like that, I think you'd have to use the full address (i.e. http://docs.plasmapy.org/en/latest/...).

Seems like a pretty good solution although annoying for local use.

I wouldn't expect it to work from jupyter; I'd like to make sure it works with a local doc build, though. If that works, I'm like 90% sure it'll work on readthedocs.

@StanczakDominik I'm a bit confused about what you mean. I'm still having a go at the Development guide :sweat_smile:.

[StanczakDominik]

Well, if you run tox -e build_docs from the cloned repository, the documentation should be built locally, on your own machine, in docs/_build/html. What I'm wondering about is whether we can use a link schema like (../api/plasmapy.formulary.braginskii.ClassicalTransport.rst) to get the built notebook examples to link to the documentation there.

I did the exact same thing to try it out and the notebooks failed to even load when I tried out the solution in the discussion.

Could you expand on that a bit more? What exactly failed?

[rocco8773]

@chttrjeankr I'd say open a PR with what you got, which will help us see your approach. Then we can help you work through the possible sphinx issues. Just make sure when you commit the notebook changes that you exclude any executed outputs.

[chttrjeankr]

What I'm wondering about is whether we can use a link schema like (../api/plasmapy.formulary.braginskii.ClassicalTransport.rst) to get the built notebook examples to link to the documentation there.

Tried this link schema in markdown. It worked after a local doc build.

Could you expand on that a bit more? What exactly failed?

I had an Unreadable Notebook NotJSONError. I figured it out though. My bad.

@chttrjeankr I'd say open a PR with what you got, which will help us see your approach.

Perfect. So, I tried out various ways of making it work and the markdown format seems to link it to the documentation without any problems (after tox -e build_docs). The syntax highlighting thing is still not fixed. I'm going to try some more variations and see what works, and then raise a PR?

[chttrjeankr]

Minor update: Tried all variations that seemed possible. The 3rd option is the only one which works the best as well as maintains consistency.

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.
- @rocco8773

I'm eager to put in the effort (not much) to set it up. AFAIU, it's only the notebooks from docs/notebooks that needs these changes, right?

[StanczakDominik]

Yeah, I believe we have no more notebooks anywhere else!