Skip to content
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.

Sign up for GitHub

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

Jump to bottom

Update notebook docs based on @carreau suggestions #1255

Merged
merged 17 commits into from
Mar 24, 2016
Merged

Update notebook docs based on @carreau suggestions #1255

merged 17 commits into from
Mar 24, 2016

Conversation

willingc
Copy link
Member

Closes #1250 #1251 #1252

I think this incorporates all the desired changes that @Carreau wanted in these issues and PRs:

  • Removed rst versions of notebooks
  • notebooks build using nbsphinx
  • Removed the Examples index notebook and replaced with a rst version since linking from notebook to notebook was not working on RTD
  • Fixed the Typesetting equations notebook so that it now displays the rendered math on RTD 🎉
  • Fixed a bunch of the notebooks including: to avoid segfaulting sphinx, to use py3 for all nbs, to avoid using multiple H1 in notebooks so contents render more neatly
  • Gotten rid of all warnings except one pesky one
  • Added notebook extensions back to the TOC.
  • Updated conda yaml to environment.yml

Here's a rendered version on RTD.

Visual of Master Table of Contents
screen shot 2016-03-23 at 8 29 03 pm

Visual of example notebooks table of contents
screen shot 2016-03-23 at 8 29 24 pm

I spent way too long on this but it fixes a bunch of loose ends that have bugged me for a while.

@Carreau, @minrk, @ellisonbg Please review. Thanks.

@willingc willingc changed the title New build Update notebook docs based on @carreau suggestions Mar 24, 2016
@ellisonbg
Copy link
Contributor

Wow, that is fantastic progress. A few questions:

What is meant by "Community Documentation?" Is that what we are using to
refer to all our docs, or just part of the docs that non-core devs wrote?

Originally the notebook based documentation was supposed to be the
documentation for the notebook - at least that is how I wrote it initially.
The only problem is that we didn't delete the other sphinx docs so now we
have things repeated in multiple places. Have we started to deduplicate the
content so that content is only in one place or the other rather than both?

Kids are here this week, so I won't have much of a chance to do an in depth
review, so I would merge and we can iterate further.

Cheers, and great work!

On Wed, Mar 23, 2016 at 8:46 PM, Carol Willing [email protected]
wrote:

Closes #1250 #1250 #1251
#1251 #1252
#1252

I think this incorporates all the desired changes that @Carreau
https://github.com/carreau wanted in these issues and PRs:

  • Removed rst versions of notebooks
  • notebooks build using nbsphinx
  • Removed the Examples index notebook and replaced with a rst version
    since linking from notebook to notebook was not working on RTD
  • Fixed the Typesetting equations notebook so that it now displays the
    rendered math on RTD [image: 🎉]
  • Fixed a bunch of the notebooks including: to avoid segfaulting
    sphinx, to use py3 for all nbs, to avoid using multiple H1 in notebooks so
    contents render more neatly
  • Gotten rid of all warnings except one pesky one
  • Added notebook extensions back to the TOC.
  • Updated conda yaml to environment.yml

Here's a rendered version on RTD
http://testnb.readthedocs.org/en/new-build/examples/Notebook/Typesetting%20Equations.html
.

Visual of Master Table of Contents
[image: screen shot 2016-03-23 at 8 29 03 pm]
https://cloud.githubusercontent.com/assets/2680980/14007828/95364840-f137-11e5-989a-903a5ce8a050.png

Visual of example notebooks table of contents
[image: screen shot 2016-03-23 at 8 29 24 pm]
https://cloud.githubusercontent.com/assets/2680980/14007829/9536556a-f137-11e5-9a20-448c1180599a.png

I spent way too long on this but it fixes a bunch of loose ends that have
bugged me for a while.

@Carreau https://github.com/carreau, @minrk https://github.com/minrk,

@ellisonbg https://github.com/ellisonbg Please review. Thanks.

You can view, comment on, or merge this pull request online at:

#1255
Commit Summary

  • Remove rst versions of nb
  • Update makefile and build configuration
  • Update the nodebook so a cell doesn't cause a segfault intentionally
  • Update TOC
  • Add frontend doc
  • Tweak notebooks for build
  • Add nbsphinx to conda yaml
  • Save notebook as py3
  • Fix some links
  • Use rst for index
  • Drop H1 to H2 in markdown
  • Add link to nbviewer at the top of the rst index
  • Fix typo
  • Try Prof. Willie Wong's code snippet
  • Added $ for mathjax
  • $ for math doc win

File Changes

Patch Links:

—
You are receiving this because you were mentioned.
Reply to this email directly or view it on GitHub
#1255

Brian E. Granger
Associate Professor of Physics and Data Science
Cal Poly State University, San Luis Obispo
@ellisonbg on Twitter and GitHub
[email protected] and [email protected]

@willingc
Copy link
Member Author

@ellisonbg Yeah, we really should move the notebooks up to the user documentation section. The community section is really a place for us to highlight great uses and community written documentation that would be helpful to others.

Have fun with the kids. O'Reilly sustainability summit was very good yesterday. It sparked a few ideas that I want to share with you and others when we meet in person.

@minrk minrk added this to the 5.0 milestone Mar 24, 2016
@minrk
Copy link
Member

minrk commented Mar 24, 2016

Thanks, @willingc! Merging here, and we can continue content discussions in subsequent PRs.

@minrk minrk merged commit 4e3a369 into jupyter:master Mar 24, 2016
@minrk minrk mentioned this pull request Mar 24, 2016
Closed
@willingc
Copy link
Member Author

Thanks @minrk. Linking notebook to notebook is one thing that is holding us back from using the notebook more in documentation. If you have any thoughts on that, please share :-) I do plan to rationalize the content as suggested by @ellisonbg.

@willingc willingc deleted the new-build branch March 24, 2016 14:20
@Carreau
Copy link
Member

Carreau commented Mar 24, 2016

Awesome ! Thanks !

@mgeier mgeier mentioned this pull request Mar 26, 2016
Merged
@mgeier
Copy link
Contributor

mgeier commented Mar 26, 2016

@willingc wrote:

Linking notebook to notebook is one thing that is holding us back [...]

What do you mean?

This should work just as it works in the live notebook and on nbviewer, see http://nbsphinx.readthedocs.org/en/latest/markdown-cells.html#Links-to-Other-Notebooks

Or am I missing something?

BTW, ipynb -> rst and rst -> ipynb should work as well, if anybody should need that.
However, links to subsections are only possible if the target is a notebook.

@mgeier
Copy link
Contributor

mgeier commented Apr 12, 2016

@willingc Did you read my comment above?

BTW, I've just made a new nbsphinx release which should handle LaTeX math environments correctly. With that, the work-around with different numbers of $ signs shouldn't be necessary anymore.

@github-actions github-actions bot locked as resolved and limited conversation to collaborators Apr 16, 2021
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Reviewers
No reviews
Assignees
No one assigned
Labels
status:resolved-locked
Projects
None yet
Milestone
5.0
Development

Successfully merging this pull request may close these issues.
5 participants
@willingc @ellisonbg @minrk @Carreau @mgeier