A few suggestions

[mgeier]

Author of nbsphinx here.

Thanks for providing this great resource and thanks for mentioning nbsphinx!

In the following, I'm referring to https://pythonpackaging.info/04-Documentation.html#Including-jupyter-notebooks-as-part-of-your-documentation.

In your usage of the toctree directive, you add the file suffixes.
This works, but only for backwards compatibility.
Nowadays, it is recommended to drop the file suffixes.
AFAIK, keeping the suffixes doesn't have any obvious disadvantages, but there is a subtle one:
People might think, when using the :glob: option, that they can use *.ipynb or example-*.ipynb or something like this. However, this will not work.
If they never use suffixes, they will properly assume that * and example-* can be used.

You are saying: "the fact that the standard text box in a notebook uses Markdown and not reStructuredText can get a little confusing".
I agree that it can be confusing.
You might want to mention that it is also possible to use Markdown files: https://www.sphinx-doc.org/en/master/usage/markdown.html
However, I know that Markdown is more limited, and some things only work with reST.

You are mentioning nbsphinx_prompt_width = 0. This will stop working when spatialaudio/nbsphinx#439 is merged.
You probably shouldn't recommend that at all, but if you insist, you should recommend one of the more reliable ways to remove prompts mentioned there: https://nbsphinx.readthedocs.io/en/latest/custom-css.html (I have just created this page).

The .ipynb_checkpoints thing is a great tip, but since spatialaudio/nbsphinx#425, and since the latest nbsphinx release 0.6.1 (from 2 days ago), this is not necessary anymore.

And finally: Since you are querying the "last changed" date of your Git repo in your conf.py, you might be interested in this little Sphinx extension I created recently: https://github.com/mgeier/sphinx-last-updated-by-git

[jobovy]

Author of nbsphinx here.

Thanks for providing this great resource and thanks for mentioning nbsphinx!

Thanks for the feedback! And thanks for nbsphinx, which is such a great resource that I use a lot!

In the following, I'm referring to https://pythonpackaging.info/04-Documentation.html#Including-jupyter-notebooks-as-part-of-your-documentation.

In your usage of the toctree directive, you add the file suffixes.
This works, but only for backwards compatibility.
Nowadays, it is recommended to drop the file suffixes.
AFAIK, keeping the suffixes doesn't have any obvious disadvantages, but there is a subtle one:
People might think, when using the :glob: option, that they can use *.ipynb or example-*.ipynb or something like this. However, this will not work.
If they never use suffixes, they will properly assume that * and example-* can be used.

Thanks for pointing this out, I didn't realize that giving the file extensions could lead to issues!

You are saying: "the fact that the standard text box in a notebook uses Markdown and not reStructuredText can get a little confusing".
I agree that it can be confusing.
You might want to mention that it is also possible to use Markdown files: https://www.sphinx-doc.org/en/master/usage/markdown.html
However, I know that Markdown is more limited, and some things only work with reST.

Thanks for this link, which I also didn't know about. I wrote this mainly out of frustration with myself! Because I was describing reST syntax in a notebook, I had to constantly remember that many of the text boxes that I was using were Markdown, while others I had to make reST to get things like reST directives to properly typeset. Anyway, I think most people who include notebooks basically only include notebooks in their setup (except perhaps for the main page), so in general it's not such an issue I think.

You are mentioning nbsphinx_prompt_width = 0. This will stop working when spatialaudio/nbsphinx#439 is merged.
You probably shouldn't recommend that at all, but if you insist, you should recommend one of the more reliable ways to remove prompts mentioned there: https://nbsphinx.readthedocs.io/en/latest/custom-css.html (I have just created this page).

Ah great, yes, I agree that CSS is a better way to deal with this!

On a related note, I also wanted to remove the prompts for the PDF (LaTeX) version, but there seems to be no way to do that in nbsphinx? I managed to remove them with this hack, but a native way to do this in nbsphinx would be useful. I think it's useful to not show prompts in things like online books, course notes, etc. where you can have lots of text and math and a less direct relation to coding in a notebook. I find the combination of sphinx + nbsphinx to be very useful for writing such documents (like these notes!), but I like to de-emphasize for users that these notes are written as notebooks, and removing the prompts is necessary for that (otherwise readers will think "What are these prompts?").

The .ipynb_checkpoints thing is a great tip, but since spatialaudio/nbsphinx#425, and since the latest nbsphinx release 0.6.1 (from 2 days ago), this is not necessary anymore.

Wonderful!

And finally: Since you are querying the "last changed" date of your Git repo in your conf.py, you might be interested in this little Sphinx extension I created recently: https://github.com/mgeier/sphinx-last-updated-by-git

That looks great, it would be great to simplify that part of my conf.py in a lot of my projects!

I hadn't been meaning to make changes to these notes in the near future, because I wrote them for a course that I was teaching that is now finished. But I'll try to find some time soon to make these edits and will leave this open until then. Thanks again

[mgeier]

Anyway, I think most people who include notebooks basically only include notebooks in their setup (except perhaps for the main page), so in general it's not such an issue I think.

I think so, too.

On a related note, I also wanted to remove the prompts for the PDF (LaTeX) version, but there seems to be no way to do that in nbsphinx?

No, there isn't.

I'm not a fan of removing the prompts, I have yet to see a situation where this would be justified.

Could you provide an example (both with and without prompts), where removing the prompts would be clearly beneficial?

Anyway, if you want to push this feature, you should do so in the nbsphinx issue tracker.

I managed to remove them with this hack, but a native way to do this in nbsphinx would be useful.

I'm unlikely to implement this myself, but if somebody makes a PR, I'll consider it.

I think it's useful to not show prompts in things like online books, course notes, etc. where you can have lots of text and math and a less direct relation to coding in a notebook.

That sounds like it could be true, I'd still like to see some examples.

I find the combination of sphinx + nbsphinx to be very useful for writing such documents (like these notes!), but I like to de-emphasize for users that these notes are written as notebooks, and removing the prompts is necessary for that (otherwise readers will think "What are these prompts?").

Isn't this a good question?

So they get curious and want to try it out themselves ...

As an alternative, you could also try https://myst-nb.readthedocs.io/, they don't seem to display the prompts at all.

[mgeier]

On a related note, I also wanted to remove the prompts for the PDF (LaTeX) version, but there seems to be no way to do that in nbsphinx?

No, there isn't.

Correction: I just found a surprisingly easy way to remove those suckers (or at least make them invisible):

latex_elements = {
    'preamble': r"""
\definecolor{nbsphinxin}{HTML}{FFFFFF}
\definecolor{nbsphinxout}{HTML}{FFFFFF}
""",
}

[jobovy]

On a related note, I also wanted to remove the prompts for the PDF (LaTeX) version, but there seems to be no way to do that in nbsphinx?

No, there isn't.

Correction: I just found a surprisingly easy way to remove those suckers (or at least make them invisible):

latex_elements = {
    'preamble': r"""
\definecolor{nbsphinxin}{HTML}{FFFFFF}
\definecolor{nbsphinxout}{HTML}{FFFFFF}
""",
}

Ah yes, that's neat!