You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Tutorial first given at ENS Ulm (January 2023) on how to develop a Python package. There is a slight focus on scientific computing, but the general principles apply to any Python project.
15
14
16
-
.. contents:: **Table of Contents**
15
+
.. |ss| raw::html
17
16
18
-
Creating virtual environment and local install
19
-
==============================================
17
+
<strike>
20
18
21
-
With `Anaconda <https://www.anaconda.com/>`__ (recommended).
22
-
After installing Anaconda or `Miniconda <https://docs.conda.io/en/latest/miniconda.html>`__ (light version), create a new environment:
19
+
.. |se| raw:: html
23
20
24
-
.. code:: bash
21
+
</strike>
25
22
26
-
# create new environment, press enter to accept
27
-
conda create -n project_env python=3.9
28
23
29
-
# view available environments
30
-
conda info --envs
24
+
Reproducibility is important for software: *if it's not reproducible,
25
+
it's not useful*. Even if you don't plan on sharing your code, imagine
26
+
coming back to a project after a few weeks, or having
27
+
to install it on a new machine. You'll be all the more thankful to your
28
+
past self if you have a clear way to install and run your code.
31
29
32
-
# activate environment
33
-
conda activate project_env
30
+
This repository is a collection of tips and tricks for developing stable
31
+
and reproducible Python code. There is a slight focus on scientific
32
+
computing, but the general principles can apply to most Python projects.
33
+
If you're reading this from GitHub, please check out the
34
+
`documentation <https://pydevtips.readthedocs.io/en/latest/>`_ for a
35
+
more in-depth explanation of the topics covered.
34
36
35
-
# install package locally
36
-
(project_env) pip install -e .
37
+
The intended audience is myself (as I often find myself going to past
38
+
projects to find how I did something!), but also for students and
39
+
anyone who is interested in learning some new tricks or even
40
+
sharing their own! I try to follow the principles laid out here on
41
+
development and reproducibility, so feel free to point out any lapses
42
+
or suggest improvements, either by opening an issue or pull request.
37
43
38
-
# deactivate environment
39
-
(project_env) conda deactivate
44
+
As is typical in open source, there are many ways to do the same thing.
45
+
But hopefully this gives you a starting point. Feel free to pick and
46
+
choose the features that you like. This flexibility is one of the best
47
+
(and worst parts) of open source. Some of the things we cover:
40
48
49
+
* Virtual environments.
50
+
* Version control.
51
+
* Reproducible examples.
52
+
* Documentation.
53
+
* Code formatting.
54
+
* Unit tests and continuous integration.
55
+
* Packaging and distribution.
56
+
* Remove development.
41
57
42
-
For machines really light on memory (e.g. Raspberry Pi) use
Code formatting is important for readability. It allows you to write code that
5
+
is easy to follow (for your future self as much as others), and (least importantly)
6
+
adheres to the `PEP8 <https://www.python.org/dev/peps/pep-0008/>`_ standard.
7
+
8
+
However, remembering all the rules and manually formatting your code is not
9
+
how we want to spend our time as developers. To this end, there are several
10
+
tools that can help us with this task. The ones we use are:
11
+
12
+
* `Black <https://github.com/psf/black>`_ which will reformat your code
13
+
in-place to conform to the PEP8 standard.
14
+
* `Flake8 <https://flake8.pycqa.org/en/latest/>`__ which is a *linter* that
15
+
will check your code for errors and style violations, but not reformat it. For
16
+
example, for me it has identified code where I have unused variables or
17
+
scripts / functions that are too long.
18
+
19
+
While you can use these tools manually, it is much more convenient to use them
20
+
as pre-commit hooks. This means that before you commit your code, these tools
21
+
will be run automatically. If they find any errors, the commit will be aborted
22
+
and you will have to fix the errors before you can commit again. Pre-commit
23
+
helps you to automate this process and avoid commits that do not conform to
24
+
the PEP8 standard (and commits that are just for formatting).
25
+
26
+
A few files are needed to setup pre-commit hooks:
27
+
28
+
* `.pre-commit-config.yaml <https://github.com/ebezzam/python-dev-tips/blob/main/.pre-commit-config.yaml>`_: This file contains the configuration for the
29
+
pre-commit hooks. It specifies which tools to use, and how to use them.
30
+
* `.flake8 <https://github.com/ebezzam/python-dev-tips/blob/main/.flake8>`_: This file contains the configuration for Flake8. It specifies
31
+
e.g. which errors to ignore, and which line length to use.
32
+
* `pyproject.toml <https://github.com/ebezzam/python-dev-tips/blob/main/pyproject.toml>`_: This file contains the configuration for Black. It
33
+
specifies e.g. which line length to use.
34
+
35
+
You can then install the pre-commit hooks for your project by running the
Copy file name to clipboardExpand all lines: docs/source/documentation.rst
+34-7
Original file line number
Diff line number
Diff line change
@@ -1,13 +1,29 @@
1
1
Documentation
2
2
=============
3
3
4
-
We will be using `Sphinx <https://www.sphinx-doc.org/en/master/>`__ to generate documentation from
5
-
docstrings that are written within code. Docstrings are long-form
4
+
*"Documentation is a love letter that you write to your future self."*
5
+
6
+
*-- Damian Conway*
7
+
8
+
Documentation is a critical part of any software project. It is the first
9
+
point of contact for new users, and it is the first place to look for
10
+
developers when they need to understand how a piece of code works. It is
11
+
also a great way to share your knowledge with the community.
12
+
13
+
*As a minimum*, it's good to have a README file that describes:
14
+
15
+
* What the project is about.
16
+
* How to install the project.
17
+
* How to use the project.
18
+
19
+
Inside your code, comments can be very useful to describe what a function or
20
+
script does. Even better, is to add `docstrings <https://peps.python.org/pep-0257/#what-is-a-docstring>`_
21
+
to your functions and classes. Docstrings are long-form
6
22
comments beneath class and functions declaration that typically describe:
7
23
8
-
- What the function or class does.
9
-
- Its inputs and their data types.
10
-
- Its outputs and their data types.
24
+
* What the function or class does.
25
+
* Its inputs and their data types.
26
+
* Its outputs and their data types.
11
27
12
28
For example:
13
29
@@ -35,7 +51,17 @@ For example:
35
51
assertisinstance(b, int)
36
52
return a + b
37
53
38
-
Which will be rendered as :func:`pydevtips.utils.add`.
54
+
A documentation generator, such as `Sphinx <https://www.sphinx-doc.org/en/master/>`__,
55
+
can then be used to render your docstrings into a static website, as shown at
56
+
:func:`pydevtips.utils.add` for the above example.
57
+
58
+
59
+
This website can be hosted *for free* on `ReadTheDocs <https://readthedocs.org/>`__ (like this!)
60
+
or on GitHub pages. It is also possible to host the documentation on your own
61
+
server.
62
+
63
+
Below we describe how to setup your project to generate documentation with Sphinx,
64
+
and how to host it on ReadTheDocs.
39
65
40
66
Initial setup
41
67
-------------
@@ -101,6 +127,7 @@ You can do a clean build of your documentation with the following commands:
101
127
102
128
.. code:: bash
103
129
130
+
# inside `docs` folder
104
131
make clean
105
132
make html
106
133
@@ -133,7 +160,7 @@ Pro-tips
133
160
* `Add the path <https://github.com/ebezzam/python-dev-tips/blob/e51dd62a2dd156fdd3e559be3930f87f2a4e6405/docs/source/conf.py#L22>`__
134
161
to your package, so that it doesn't have to be installed (again keeping your documentation environment light!).
135
162
* `Automate year <https://github.com/ebezzam/python-dev-tips/blob/e51dd62a2dd156fdd3e559be3930f87f2a4e6405/docs/source/conf.py#L32>`__.
136
-
163
+
* You can reference other sections in your documentation by their title, e.g. :ref:`like this <Code formatting>` with ``:ref:`like this <Code formatting>``.
0 commit comments