How to contribute¶
Author: Nicolas Rougier
If you spot typos, unclear or clumsy wording in the lectures, please help to improve them. Simple text editing can be done by editing files in your GitHub fork of the lectures. On every html page of the lectures, an edit button on the top right links to the editable source of the page (you still need to create a fork of the project). Edit the source and choose “Create a new branch for this commit and start a pull request”.
Choose a topic that is not yet covered and write it up !
First create a new issue on GitHub to explain the topic which you would like to cover, in order to discuss with editors and contributors about the scope of the future tutorial.
Then create a new directory inside one of the chapters directories (
packages) and create a file
index.rstfor the new tutorial. Add the new file in the table of contents of the corresponding chapter (in its
Keep in mind that tutorials are to be taught at different places and different parts may be combined into a course on Python for scientific computing. Thus you want them to be interactive and reasonably short (one to two hours).
Last but not least, the goal of this material is to provide a concise text to learn the main features of the scientific Python ecosystem. If you want to contribute to reference material, we suggest that you contribute to the documentation of the specific packages that you are interested in.
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 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.
Several resources are available online to learn git and GitHub, such as https://try.github.io for complete beginners.
Please refrain from modifying the Makefile unless it is absolutely necessary.
The HTML output is used for displaying on screen while teaching. The goal
is to have the same material displayed as in the notes. Thus there needs
to be a very concise display, with bullet-lists rather than full-blown
paragraphs and sentences. For more elaborate discussions that people can
read and refer to, please use the
tip sphinx directive. It creates
collapsible paragraphs, that can be hidden during an oral
.. tip:: Here insert a full-blown discussion, that will be collapsible in the HTML version. It can span on multiple paragraphs
This renders as:
Here insert a full-blown discussion, that will be collapsible in the HTML version.
It can span on multiple paragraphs
We do not check figures in the repository.
Any figure must be generated from a python script that needs to be named
plot_xxx.py (xxx can be anything of course) and put into the
directory. The generated image will be named from the script name.
This is the way to include your image and link it to the code:
.. image:: auto_examples/images/sphx_glr_plot_simple_001.png :target: auto_examples/plot_simple.html
You can display the corresponding code using the
""" A simple example ================= """ import numpy as np import matplotlib.pyplot as plt X = np.linspace(-np.pi, np.pi, 100) Y = np.sin(X) plt.plot(X, Y, linewidth=2) plt.show()
The transformation of Python scripts into figures and galleries of examples is provided by the sphinx-gallery package.
There are three main kinds of markup that should be used: italics, bold
fixed-font. Italics should be used when introducing a new technical
term, bold should be used for emphasis and
fixed-font for source code.
In restructured-text markup this is:
when using *object-oriented programming* in Python you **must** use the ``class`` keyword to define your *classes*.
Try to avoid to go below paragraph granularity or your document might become difficult to read:
============= Chapter title ============= Sample content. Section ======= Subsection ---------- Paragraph ......... And some text.
This is a note
This is a warning
Figures positioned with :align: right are float. To flush them, use: