/scipy-cookbook

Scipy Cookbook

Primary LanguageJupyter NotebookOtherNOASSERTION

Scipy Cookbook

This is a conversion and second life of SciPy Cookbook (previously at http://wiki.scipy.org/Cookbook/); as a bunch of Ipython notebooks.

It can be found live at http://scipy-cookbook.readthedocs.org/

Contributing

Add new notebooks or fix old ones by sending pull requests

Alternatively open an issue and attach (drag-and-drop) a fixed notebook file.

  • The ipython/ directory contains IPython notebooks.
  • Each notebook should start with a title (Markdown # Some title).
  • Notebooks can be categorized by adding Markdown text TAGS: Name of section (on a single line). Try to stick with existing sections, if reasonable.
  • Notebooks can include author name, by adding Markdown text AUTHORS: Some Name; Another Name (on a single line).

Run python build.py --html to generate HTML output to _build/html.

The conversion of the wiki content was originally done by Matti Pastell: https://github.com/mpastell/SciPy-CookBook

Janitorial tasks

Much of the old wiki content is outdated, so if someone has huge amounts of extra time on their hands, going through them could be useful.

Before starting, check out the list of pull requests and issues here to avoid doing duplicate work. You can see which files have been already modified by looking at here: https://github.com/scipy/scipy-cookbook/tree/master/ipython. It's also worth checking https://github.com/scipy/scipy-cookbook/network to see if there are any in-progress branches uploaded to Github which haven't yet been merged.

Your help is both needed and appreciated. The quick way to get started is to fork this repo, and then do

git clone git@github.com:YOURUSERNAME/SciPy-CookBook.git
cd SciPy-CookBook
git remote add upstream https://github.com/scipy/scipy-cookbook.git
cd ipython

and then switch to a new branch

git checkout -b edit-xxx
git fetch upstream
git reset --hard upstream/master

after which

ipython notebook
# edit notebook XXX in ipython web notebook and save
git commit -m "Fix up notebook XXX" -a
git push origin edit-xxx

and then browse to your github repo page and send the fixed version as a pull request.

If you however cannot be arsed to use git, just upload the file somewhere (e.g. gist.github.com) and file a new issue and tell which file you changed and include a link to the uploaded file. Thanks!

What to fix

The Ipython notebook conversion is not fully flawless, and cannot be fully automated. What needs to be done is:

  • Ensure the code examples are runnable.

  • Ensure the image links are correct (look for malformatted [...](...) in the markdown text blocks --- the conversion didn't always treat these correctly).

    Local files and images should be linked to via standard Markdown syntax [link text](files/attachments/NotebookName/filename) and ![](files/attachments/NotebookName/image.png)

  • Ensure each notebook begins with a top-level heading with a title for the snippet. Avoid using other top-level headings in the rest of the notebooks. (This should be the case currently.)

  • Replace image attachments with the images generated by the plotting commands in the examples themselves, where appropriate.

  • Remove unnecessary file attachments, where appropriate (remember that the ipython notebooks can be converted to scripts easily, and the purpose is more to distribute code snippets rather than full modules).

  • Remove obviously useless (e.g. empty) files.

  • Obviously outdated content should get a short notice on top, with a date of the last update on http://wiki.scipy.org/

    Also add TAGS: Outdated so that it goes to the outdated section.

  • If some entry is too incomplete to fix (e.g. math formulas), look at the source version at http://wiki.scipy.org/Cookbook/

  • Compare against the original wiki version under original/. Check if a part of the text at the end is missing.

  • And other things. Note, however, that the point is more to fix surface issues than to try to rewrite things in a better way.