This sounds good to me. So it would look something like this: - All of our git tracked examples will be in .ipnb format. - The test script calls nbconvert on the examples, and runs the .py files. These are not tracked by git. - At release time, we use nbconvert to convert the notebook files to pdf. Both the notebooks and the pdfs are shipped with the release (this way, people without the notebook can still read the examples). We could do html or .py instead of pdf if that ends up being better. Ideally this script would be automated, but it's not a big deal, because we only have to do it when we release, so whatever the workflow is just needs to be in https://github.com/sympy/sympy/wiki/New-Release.
So the main thing to do is: 1. Figure out all the nbconvert stuff. Make sure that it all works, and if not try to fix it (or get the IPython guys to). 2. Convert all our examples to the notebook format. 3. Update our examples testing to use nbconvert. Point 2 will probably take the most time, especially if you take the time to make the notebooks look nice. Feel free to completely revamp them. Point 1 may or may not take time. It depends on how many bugs there are in nbconvert. There may also be subtleties involved with testing. Point 3 should be trivial by the time points 1 and 2 are figured out. Am I missing any key points here? Oh, and one more thing: make sure to make the notebooks in IPython 0.12, not the git master, as the git master is backward incompatible with 0.12 (unless they release 0.13 before we get to 0.7.3). Aaron Meurer On Sat, Apr 28, 2012 at 12:17 PM, [email protected] <[email protected]> wrote: > This has cropped up a number of times already. The main points: > > - ipython notebooks are great for examples from pedagogical point of view > - there is no standard way to run tests on them > - there is no standard way to add them to sphinx docs (this > http://matplotlib.sourceforge.net/sampledoc/ipython_directive.html is > for ipython scripts, not for complete notebooks) > > I propose that we become early adopters of > https://github.com/ipython/nbconvert which seems to be how the ipython > team plans to address these issues. (correct me if I am wrong) > > The proposal: > - a simple check added to whatever tests the examples at the moment - > if nbconvert is installed it uses it to generate .py files and test > them > - a simple script added to the makefile for the docs that detects if > nbconvert is installed and generates html or whatever to be added to > the docs > > Please keep in mind that anything more feature complete than this > proposal will take disproportionately more time to implement at the > moment. When the tools like nbconvert mature we may switch to a better > workflow. > > I can try to take care of this in a week after my exams if there is > interest in the proposal. > > -- > You received this message because you are subscribed to the Google Groups > "sympy" group. > To post to this group, send email to [email protected]. > To unsubscribe from this group, send email to > [email protected]. > For more options, visit this group at > http://groups.google.com/group/sympy?hl=en. > -- You received this message because you are subscribed to the Google Groups "sympy" group. To post to this group, send email to [email protected]. To unsubscribe from this group, send email to [email protected]. For more options, visit this group at http://groups.google.com/group/sympy?hl=en.
