Add to documentation the use of raw cells when discussing links to *.rst files with domain objects (example_python_function)

[1kastner]

Hello there and thanks a lot for this great project! This was exactly what I was searching for. I love the feature that the Jupyter Notebook can be tried out, it is a well-supported technology and I can embed it into my documentation.

First, I struggled a bit about how to include the references to the remaining Sphinx documentation because in https://nbsphinx.readthedocs.io/en/0.8.8/markdown-cells.html#Links-to-*.rst-Files-(and-Other-Sphinx-Source-Files), an approach is used that I found a bit counter-intuitive. But after a bit of searching I found the Raw Cells that allow me to create links the Sphinx way! So I was wondering whether the documentation could be clearer at this point? I would love to see there that two approaches exist. Either one can create the links manually (as nicely discussed at https://nbsphinx.readthedocs.io/en/0.8.8/a-normal-rst-file.html#links-to-notebooks-and-other-sphinx-source-files) or one can decide to live with less beautiful Jupyter Notebooks that contain ReST code but which smoothly integrates with the Sphinx documentation. The second one could maybe be another section in the same document?

[mgeier]

Yes, that's a good idea, would you like to make a PR for this?

[1kastner]

Sure, I will create a draft soon.

[1kastner]

That was my first light-weight idea. It only adds a few lines that hopefully help future readers.