This repository gathers some lecture notes on the scientific Python ecosystem that can be used for a full course of scientific computing with Python.
These documents are written with the rest markup language (.rst extension) and built using Sphinx: http://sphinx.pocoo.org/.
As stated in the LICENSE.txt file, this material comes with no strings attached. Feel free to reuse and modify for your own teaching purposes.
However, we would like this reference material to be improved over time, thus we encourage people to contribute back changes. These will be reviewed and edited by the original authors.
To generate the html output for on-screen display, Type:
make html
the generated html files can be found in build/html
The first build takes a long time, but information is cached and subsequent builds will be faster.
To generate the pdf file for printing:
make pdf
The pdf builder is a bit pointy and you might have some TeX errors. Tweaking the layout in the rst files is usually enough to work around these problems.
probably incomplete
- make
- sphinx (>= 1.0)
- pdflatex
- pdfjam
- matplotlib
- scikit-learn (>= 0.8)
There are three main kinds of markup that should be used: italics, bold
and fixed-font. Italics should be used when introducing a new technical
term, bold should be used for emphasis and fixed-font for source code.
Example:
When using object-oriented programming in Python you must use the
class keyword to define your classes.
In restructured-text markup this is:
when using *object-oriented programming* in Python you **must** use the ``class`` keyword to define your *classes*.
For cross-referencing API documentation we prefer to use the intersphinx extension. This provides the directives :mod:, :class: and :func: to cross-link to modules, classes and functions respectively.
The easiest way to make your own version of this teaching material is to fork it under Github, and use the git version control system to maintain your own fork. For this, all you have to do is create an account on github (this site) and click on the fork button, on the top right of this page. You can use git to pull from your fork, and push back to it the changes. If you want to contribute the changes back, just fill a pull request, using the button on the top of your fork's page.
Please refrain from modifying the Makefile unless it is absolutely necessary.
The figure should be generated from Python source files. The policy is
to create an examples directory, in which you put the corresponding
Python files. Any files with a name starting with plot_ will be run
during the build process, and figures created by matplotlib will be saved
as images in an auto_examples directory. You can use these to include
in the document as figures. To display the code snippet, you can use the
literal-include directive. Any additional data needed by the plotting script
should be included in the same directory. NB: the code to provide this style of
plot inclusion was adopted from the scikits.learn project and can be found in
sphinxext/gen_rst.py.
Contributing guide and chapter example
The directory guide contains an example chapter with specific instructions on how to contribute:
.. toctree:: guide/index.rst