-
Notifications
You must be signed in to change notification settings - Fork 3
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
A few suggestions #1
Comments
Thanks for the feedback! And thanks for
Thanks for pointing this out, I didn't realize that giving the file extensions could lead to issues!
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.
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
Wonderful!
That looks great, it would be great to simplify that part of my 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 |
I think so, too.
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
I'm unlikely to implement this myself, but if somebody makes a PR, I'll consider it.
That sounds like it could be true, I'd still like to see some examples.
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. |
Correction: I just found a surprisingly easy way to remove those suckers (or at least make them invisible):
|
Ah yes, that's neat! |
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
orexample-*.ipynb
or something like this. However, this will not work.If they never use suffixes, they will properly assume that
*
andexample-*
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 latestnbsphinx
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-gitThe text was updated successfully, but these errors were encountered: