From 7e4cc6f511154ee0d915de81ecee44a9fe087db7 Mon Sep 17 00:00:00 2001
From: Repo Updater <noreply@mpcdf.mpg.de>
Date: Fri, 1 Oct 2021 16:31:20 +0200
Subject: [PATCH] 76c061fb some work on the software engineering part
---
examples/profiling/diffusion_numba.py | 9 +-
.../setuptools/hello_world/HelloWorld/lib.py | 4 -
.../hello_world_with_sphinx/setup.py | 18 ---
.../HelloWorld/__init__.py | 2 -
.../hello_world_with_tests/say_hello.py | 3 -
.../setuptools/minimal/helloworld/__init__.py | 2 +
examples/setuptools/minimal/helloworld/lib.py | 4 +
examples/setuptools/minimal/say_hello.py | 3 +
examples/setuptools/minimal/setup.py | 20 +++
.../HelloWorld/__init__.py | 0
.../HelloWorld/lib.py | 0
.../README.txt | 0
.../{hello_world => py-test}/say_hello.py | 0
.../setup.py | 0
.../tests/test_eigen.py | 0
.../tests/test_helloworld.py | 0
.../HelloWorld/__init__.py | 0
.../HelloWorld/lib.py | 0
.../README.txt | 0
.../doc/Makefile | 0
.../doc/_build/_placeholder | 0
.../doc/_placeholder | 0
.../doc/_static/_placeholder | 0
.../doc/_templates/_placeholder | 0
.../doc/conf.py | 0
.../doc/index.rst | 0
.../doc/make.bat | 0
.../say_hello.py | 0
.../setup.cfg | 0
.../{hello_world => sphinx-doc}/setup.py | 0
notebooks/2e--Interfacing_with_C_and_F.ipynb | 2 +-
notebooks/3a--Profiling.ipynb | 14 +-
notebooks/3b--Software_Engineering.ipynb | 125 ++++++++++++------
33 files changed, 125 insertions(+), 81 deletions(-)
delete mode 100644 examples/setuptools/hello_world/HelloWorld/lib.py
delete mode 100644 examples/setuptools/hello_world_with_sphinx/setup.py
delete mode 100644 examples/setuptools/hello_world_with_tests/HelloWorld/__init__.py
delete mode 100755 examples/setuptools/hello_world_with_tests/say_hello.py
create mode 100644 examples/setuptools/minimal/helloworld/__init__.py
create mode 100644 examples/setuptools/minimal/helloworld/lib.py
create mode 100755 examples/setuptools/minimal/say_hello.py
create mode 100644 examples/setuptools/minimal/setup.py
rename examples/setuptools/{hello_world => py-test}/HelloWorld/__init__.py (100%)
rename examples/setuptools/{hello_world_with_tests => py-test}/HelloWorld/lib.py (100%)
rename examples/setuptools/{hello_world_with_tests => py-test}/README.txt (100%)
rename examples/setuptools/{hello_world => py-test}/say_hello.py (100%)
rename examples/setuptools/{hello_world_with_tests => py-test}/setup.py (100%)
rename examples/setuptools/{hello_world_with_tests => py-test}/tests/test_eigen.py (100%)
rename examples/setuptools/{hello_world_with_tests => py-test}/tests/test_helloworld.py (100%)
rename examples/setuptools/{hello_world_with_sphinx => sphinx-doc}/HelloWorld/__init__.py (100%)
rename examples/setuptools/{hello_world_with_sphinx => sphinx-doc}/HelloWorld/lib.py (100%)
rename examples/setuptools/{hello_world_with_sphinx => sphinx-doc}/README.txt (100%)
rename examples/setuptools/{hello_world_with_sphinx => sphinx-doc}/doc/Makefile (100%)
rename examples/setuptools/{hello_world_with_sphinx => sphinx-doc}/doc/_build/_placeholder (100%)
rename examples/setuptools/{hello_world_with_sphinx => sphinx-doc}/doc/_placeholder (100%)
rename examples/setuptools/{hello_world_with_sphinx => sphinx-doc}/doc/_static/_placeholder (100%)
rename examples/setuptools/{hello_world_with_sphinx => sphinx-doc}/doc/_templates/_placeholder (100%)
rename examples/setuptools/{hello_world_with_sphinx => sphinx-doc}/doc/conf.py (100%)
rename examples/setuptools/{hello_world_with_sphinx => sphinx-doc}/doc/index.rst (100%)
rename examples/setuptools/{hello_world_with_sphinx => sphinx-doc}/doc/make.bat (100%)
rename examples/setuptools/{hello_world_with_sphinx => sphinx-doc}/say_hello.py (100%)
rename examples/setuptools/{hello_world_with_sphinx => sphinx-doc}/setup.cfg (100%)
rename examples/setuptools/{hello_world => sphinx-doc}/setup.py (100%)
diff --git a/examples/profiling/diffusion_numba.py b/examples/profiling/diffusion_numba.py
index bcaa96b..bba337e 100755
--- a/examples/profiling/diffusion_numba.py
+++ b/examples/profiling/diffusion_numba.py
@@ -4,7 +4,7 @@
import numpy as np
-from numba import jit
+from numba import jit, njit
# parameters (global, for convenience)
n_iterations = 10
@@ -33,11 +33,11 @@ def init(val=0.5):
return grid
-@jit(nopython=True)
def main_loop(evolve_func, grid):
"""Main loop function, calling evolve_func on grid."""
grid_tmp = np.empty_like(grid)
for i in range(1, n_iterations+1):
+ apply_periodic_bc_python(grid, n_points)
evolve_func(grid, grid_tmp, n_points, dt, D)
# swap references, do not copy
if grid_tmp is not None:
@@ -47,7 +47,7 @@ def main_loop(evolve_func, grid):
return grid
-@jit(nopython=True)
+@njit()
def apply_periodic_bc_python(grid, n_points):
"""Explicitly apply periodic boundary conditions, via Python loops."""
for j in range(n_points + 2):
@@ -58,9 +58,8 @@ def apply_periodic_bc_python(grid, n_points):
grid[ i, 0] = grid[ i,-2]
-@jit(nopython=True)
+@njit
def evolve_python(grid, grid_tmp, n_points, dt, D):
- apply_periodic_bc_python(grid, n_points)
for i in range(1, n_points+1):
for j in range(1, n_points+1):
# stencil formula
diff --git a/examples/setuptools/hello_world/HelloWorld/lib.py b/examples/setuptools/hello_world/HelloWorld/lib.py
deleted file mode 100644
index e24c9cf..0000000
--- a/examples/setuptools/hello_world/HelloWorld/lib.py
+++ /dev/null
@@ -1,4 +0,0 @@
-# implementation file, part of the "HelloWorld" demo Python package
-
-def say_hello():
- print("Hello World!")
diff --git a/examples/setuptools/hello_world_with_sphinx/setup.py b/examples/setuptools/hello_world_with_sphinx/setup.py
deleted file mode 100644
index bcc7609..0000000
--- a/examples/setuptools/hello_world_with_sphinx/setup.py
+++ /dev/null
@@ -1,18 +0,0 @@
-from setuptools import setup
-setup(
- name="HelloWorld",
- version="0.1",
- # specify a list of the packages (subdirectory with __init__.py file)
- packages=["HelloWorld"],
- # executable that comes with the package (if applicable)
- scripts=['say_hello.py'],
- # software dependencies (if necessary)
- # install_requires=['docutils>=0.3'],
- # metadata for upload to PyPI
- author="Me",
- author_email="me@example.com",
- description="This is an Example Package",
- license="PSF",
- keywords="hello world example examples",
- url="http://example.com/HelloWorld/", # project home page, if any
-)
diff --git a/examples/setuptools/hello_world_with_tests/HelloWorld/__init__.py b/examples/setuptools/hello_world_with_tests/HelloWorld/__init__.py
deleted file mode 100644
index 2cd918e..0000000
--- a/examples/setuptools/hello_world_with_tests/HelloWorld/__init__.py
+++ /dev/null
@@ -1,2 +0,0 @@
-# init file of the HelloWorld example package, is automatically executed at 'import'
-from .lib import *
diff --git a/examples/setuptools/hello_world_with_tests/say_hello.py b/examples/setuptools/hello_world_with_tests/say_hello.py
deleted file mode 100755
index 47f1202..0000000
--- a/examples/setuptools/hello_world_with_tests/say_hello.py
+++ /dev/null
@@ -1,3 +0,0 @@
-#!/usr/bin/env python3
-import HelloWorld
-HelloWorld.say_hello()
diff --git a/examples/setuptools/minimal/helloworld/__init__.py b/examples/setuptools/minimal/helloworld/__init__.py
new file mode 100644
index 0000000..a66f923
--- /dev/null
+++ b/examples/setuptools/minimal/helloworld/__init__.py
@@ -0,0 +1,2 @@
+# init file of the helloworld example package, is automatically executed at 'import'
+from .lib import *
diff --git a/examples/setuptools/minimal/helloworld/lib.py b/examples/setuptools/minimal/helloworld/lib.py
new file mode 100644
index 0000000..01e41e7
--- /dev/null
+++ b/examples/setuptools/minimal/helloworld/lib.py
@@ -0,0 +1,4 @@
+# implementation file, part of the "helloworld" demo Python package
+
+def say_hello():
+ print("Hello World!")
diff --git a/examples/setuptools/minimal/say_hello.py b/examples/setuptools/minimal/say_hello.py
new file mode 100755
index 0000000..764c141
--- /dev/null
+++ b/examples/setuptools/minimal/say_hello.py
@@ -0,0 +1,3 @@
+#!/usr/bin/env python3
+import helloworld
+helloworld.say_hello()
diff --git a/examples/setuptools/minimal/setup.py b/examples/setuptools/minimal/setup.py
new file mode 100644
index 0000000..5c1e25c
--- /dev/null
+++ b/examples/setuptools/minimal/setup.py
@@ -0,0 +1,20 @@
+from setuptools import setup
+
+setup(
+ # name of the software package (as it would appear on PyPI)
+ name="helloworld",
+ version="0.1",
+ # list of the Python modules provided by the package
+ packages=["helloworld"],
+ # list of executable(s) that come with the package (if applicable)
+ scripts=['say_hello.py'],
+ # list of package dependencies (if necessary)
+ #install_requires=['numpy'],
+ # more information, necessary for an upload to PyPI
+ author="John Doe",
+ author_email="john.doe@example.mpg.de",
+ description="example package that prints hello world",
+ license="PSF",
+ keywords="hello world example",
+ url="https://example.mpg.de/helloworld/", # project home page, if any
+)
diff --git a/examples/setuptools/hello_world/HelloWorld/__init__.py b/examples/setuptools/py-test/HelloWorld/__init__.py
similarity index 100%
rename from examples/setuptools/hello_world/HelloWorld/__init__.py
rename to examples/setuptools/py-test/HelloWorld/__init__.py
diff --git a/examples/setuptools/hello_world_with_tests/HelloWorld/lib.py b/examples/setuptools/py-test/HelloWorld/lib.py
similarity index 100%
rename from examples/setuptools/hello_world_with_tests/HelloWorld/lib.py
rename to examples/setuptools/py-test/HelloWorld/lib.py
diff --git a/examples/setuptools/hello_world_with_tests/README.txt b/examples/setuptools/py-test/README.txt
similarity index 100%
rename from examples/setuptools/hello_world_with_tests/README.txt
rename to examples/setuptools/py-test/README.txt
diff --git a/examples/setuptools/hello_world/say_hello.py b/examples/setuptools/py-test/say_hello.py
similarity index 100%
rename from examples/setuptools/hello_world/say_hello.py
rename to examples/setuptools/py-test/say_hello.py
diff --git a/examples/setuptools/hello_world_with_tests/setup.py b/examples/setuptools/py-test/setup.py
similarity index 100%
rename from examples/setuptools/hello_world_with_tests/setup.py
rename to examples/setuptools/py-test/setup.py
diff --git a/examples/setuptools/hello_world_with_tests/tests/test_eigen.py b/examples/setuptools/py-test/tests/test_eigen.py
similarity index 100%
rename from examples/setuptools/hello_world_with_tests/tests/test_eigen.py
rename to examples/setuptools/py-test/tests/test_eigen.py
diff --git a/examples/setuptools/hello_world_with_tests/tests/test_helloworld.py b/examples/setuptools/py-test/tests/test_helloworld.py
similarity index 100%
rename from examples/setuptools/hello_world_with_tests/tests/test_helloworld.py
rename to examples/setuptools/py-test/tests/test_helloworld.py
diff --git a/examples/setuptools/hello_world_with_sphinx/HelloWorld/__init__.py b/examples/setuptools/sphinx-doc/HelloWorld/__init__.py
similarity index 100%
rename from examples/setuptools/hello_world_with_sphinx/HelloWorld/__init__.py
rename to examples/setuptools/sphinx-doc/HelloWorld/__init__.py
diff --git a/examples/setuptools/hello_world_with_sphinx/HelloWorld/lib.py b/examples/setuptools/sphinx-doc/HelloWorld/lib.py
similarity index 100%
rename from examples/setuptools/hello_world_with_sphinx/HelloWorld/lib.py
rename to examples/setuptools/sphinx-doc/HelloWorld/lib.py
diff --git a/examples/setuptools/hello_world_with_sphinx/README.txt b/examples/setuptools/sphinx-doc/README.txt
similarity index 100%
rename from examples/setuptools/hello_world_with_sphinx/README.txt
rename to examples/setuptools/sphinx-doc/README.txt
diff --git a/examples/setuptools/hello_world_with_sphinx/doc/Makefile b/examples/setuptools/sphinx-doc/doc/Makefile
similarity index 100%
rename from examples/setuptools/hello_world_with_sphinx/doc/Makefile
rename to examples/setuptools/sphinx-doc/doc/Makefile
diff --git a/examples/setuptools/hello_world_with_sphinx/doc/_build/_placeholder b/examples/setuptools/sphinx-doc/doc/_build/_placeholder
similarity index 100%
rename from examples/setuptools/hello_world_with_sphinx/doc/_build/_placeholder
rename to examples/setuptools/sphinx-doc/doc/_build/_placeholder
diff --git a/examples/setuptools/hello_world_with_sphinx/doc/_placeholder b/examples/setuptools/sphinx-doc/doc/_placeholder
similarity index 100%
rename from examples/setuptools/hello_world_with_sphinx/doc/_placeholder
rename to examples/setuptools/sphinx-doc/doc/_placeholder
diff --git a/examples/setuptools/hello_world_with_sphinx/doc/_static/_placeholder b/examples/setuptools/sphinx-doc/doc/_static/_placeholder
similarity index 100%
rename from examples/setuptools/hello_world_with_sphinx/doc/_static/_placeholder
rename to examples/setuptools/sphinx-doc/doc/_static/_placeholder
diff --git a/examples/setuptools/hello_world_with_sphinx/doc/_templates/_placeholder b/examples/setuptools/sphinx-doc/doc/_templates/_placeholder
similarity index 100%
rename from examples/setuptools/hello_world_with_sphinx/doc/_templates/_placeholder
rename to examples/setuptools/sphinx-doc/doc/_templates/_placeholder
diff --git a/examples/setuptools/hello_world_with_sphinx/doc/conf.py b/examples/setuptools/sphinx-doc/doc/conf.py
similarity index 100%
rename from examples/setuptools/hello_world_with_sphinx/doc/conf.py
rename to examples/setuptools/sphinx-doc/doc/conf.py
diff --git a/examples/setuptools/hello_world_with_sphinx/doc/index.rst b/examples/setuptools/sphinx-doc/doc/index.rst
similarity index 100%
rename from examples/setuptools/hello_world_with_sphinx/doc/index.rst
rename to examples/setuptools/sphinx-doc/doc/index.rst
diff --git a/examples/setuptools/hello_world_with_sphinx/doc/make.bat b/examples/setuptools/sphinx-doc/doc/make.bat
similarity index 100%
rename from examples/setuptools/hello_world_with_sphinx/doc/make.bat
rename to examples/setuptools/sphinx-doc/doc/make.bat
diff --git a/examples/setuptools/hello_world_with_sphinx/say_hello.py b/examples/setuptools/sphinx-doc/say_hello.py
similarity index 100%
rename from examples/setuptools/hello_world_with_sphinx/say_hello.py
rename to examples/setuptools/sphinx-doc/say_hello.py
diff --git a/examples/setuptools/hello_world_with_sphinx/setup.cfg b/examples/setuptools/sphinx-doc/setup.cfg
similarity index 100%
rename from examples/setuptools/hello_world_with_sphinx/setup.cfg
rename to examples/setuptools/sphinx-doc/setup.cfg
diff --git a/examples/setuptools/hello_world/setup.py b/examples/setuptools/sphinx-doc/setup.py
similarity index 100%
rename from examples/setuptools/hello_world/setup.py
rename to examples/setuptools/sphinx-doc/setup.py
diff --git a/notebooks/2e--Interfacing_with_C_and_F.ipynb b/notebooks/2e--Interfacing_with_C_and_F.ipynb
index 39ac47d..33de631 100644
--- a/notebooks/2e--Interfacing_with_C_and_F.ipynb
+++ b/notebooks/2e--Interfacing_with_C_and_F.ipynb
@@ -271,7 +271,7 @@
" * Pass NumPy arrays down to C code to perform computation, \n",
" and get the result back as a NumPy array\n",
" * Leave the memory management to the Python/NumPy layer\n",
- "* See the comprehensive example in the directory `cython/c_numpy`"
+ "* See the example in the directory `cython/c_numpy`"
]
},
{
diff --git a/notebooks/3a--Profiling.ipynb b/notebooks/3a--Profiling.ipynb
index 9684bfb..96eca77 100644
--- a/notebooks/3a--Profiling.ipynb
+++ b/notebooks/3a--Profiling.ipynb
@@ -11,7 +11,7 @@
"# Profiling\n",
"**Python for HPC course**\n",
"\n",
- "Sebastian Ohlmann, Klaus Reuter\n",
+ "2018-2021 Sebastian Ohlmann, Klaus Reuter\n",
"\n",
"Max Planck Computing and Data Facility, Garching"
]
@@ -176,7 +176,7 @@
"### timeit module\n",
"* timeit runs a function several times to get statistics about its runtime\n",
"* Part of the standard library, usable from the command line \n",
- " https://docs.python.org/3.8/library/timeit.html\n",
+ " https://docs.python.org/3.9/library/timeit.html\n",
"* Convenient usage from Jupyter notebook or ipython"
]
},
@@ -274,10 +274,10 @@
"import numpy as np\n",
"import cProfile, pstats\n",
"profile = cProfile.Profile()\n",
- "profile.enable()\n",
+ "profile.enable() # --- start profiling\n",
"M = np.random.rand(1024,1024)\n",
"S = np.sin(M)\n",
- "profile.disable()\n",
+ "profile.disable() # --- stop profiling\n",
"profile.create_stats()\n",
"with open(\"profile.txt\", 'w') as fp:\n",
" stats = pstats.Stats(profile, stream=fp)\n",
@@ -347,10 +347,10 @@
"source": [
"## line_profiler\n",
"* `line_profiler` allows to measure the cost of each single line of code\n",
- "* https://github.com/rkern/line_profiler\n",
"* Obtain `line_profiler` first via \n",
" `pip install --user line_profiler`\n",
- "* See the example in the folder `profiling`"
+ "* See the example in the folder `profiling`\n",
+ "* https://github.com/rkern/line_profiler"
]
},
{
@@ -571,7 +571,7 @@
"name": "python",
"nbconvert_exporter": "python",
"pygments_lexer": "ipython3",
- "version": "3.8.3"
+ "version": "3.8.8"
}
},
"nbformat": 4,
diff --git a/notebooks/3b--Software_Engineering.ipynb b/notebooks/3b--Software_Engineering.ipynb
index f924be4..6d93dd8 100644
--- a/notebooks/3b--Software_Engineering.ipynb
+++ b/notebooks/3b--Software_Engineering.ipynb
@@ -11,7 +11,7 @@
"# Software Engineering\n",
"**Python for HPC course**\n",
"\n",
- "Sebastian Ohlmann, Klaus Reuter\n",
+ "2018-2021 Sebastian Ohlmann, Klaus Reuter\n",
"\n",
"Max Planck Computing and Data Facility, Garching"
]
@@ -57,7 +57,7 @@
"## Software Packaging\n",
"* Python provides a standard way of software packaging\n",
" * great for \"professional\" software distribution\n",
- " * create zipfiles, tarballs, wheel, or egg packages automatically\n",
+ " * create zipfiles, tarballs, wheel, or egg packages easily\n",
" * https://packaging.python.org/\n",
"* `setup.py` using the `distutils` or `setuptools` packages\n",
" * Information on version, status, authorship, licensing, dependencies\n",
@@ -88,21 +88,22 @@
"```python\n",
"from setuptools import setup\n",
"setup(\n",
- " name=\"HelloWorld\",\n",
+ " # name of the software package (as it would appear on PyPI)\n",
+ " name=\"helloworld\",\n",
" version=\"0.1\",\n",
- " # specify a list of the packages (subdirectory with __init__.py file)\n",
- " packages=[\"HelloWorld\"],\n",
- " # executable that comes with the package (if applicable)\n",
+ " # list of the Python modules provided by the package\n",
+ " packages=[\"helloworld\"],\n",
+ " # list of executable(s) that come with the package (if applicable)\n",
" scripts=['say_hello.py'],\n",
- " # software dependencies (if necessary)\n",
- " # install_requires=['docutils>=0.3'],\n",
- " # metadata for upload to PyPI\n",
- " author=\"Me\",\n",
- " author_email=\"me@example.com\",\n",
- " description=\"This is an Example Package\",\n",
+ " # list of package dependencies (if necessary)\n",
+ " #install_requires=['numpy'],\n",
+ " # more information, necessary for an upload to PyPI\n",
+ " author=\"John Doe\",\n",
+ " author_email=\"john.doe@example.mpg.de\",\n",
+ " description=\"example package that prints hello world\",\n",
" license=\"PSF\",\n",
- " keywords=\"hello world example examples\",\n",
- " url=\"http://example.com/HelloWorld/\", # project home page, if any\n",
+ " keywords=\"hello world example\",\n",
+ " url=\"https://example.mpg.de/helloworld/\", # project home page, if any\n",
")\n",
"```"
]
@@ -118,7 +119,7 @@
"### Usage of setup.py\n",
"* Install package with `python setup.py install --user`<br>\n",
" $\\to$ installation path under `~/.local/lib/...`\n",
- "* This will make the package available for your user\n",
+ "* This will make the package available for your local user\n",
"* Build package including extensions with `python setup.py build`\n",
"* Create distribution packages for sharing\n",
" * Source package with `python setup.py sdist`\n",
@@ -134,15 +135,38 @@
},
"source": [
"### Advantages of using `setup.py`\n",
- "* Easy installation to arbitrary locations\n",
+ "\n",
+ "* Easy package installation to arbitrary locations\n",
"* Better handling of different versions\n",
- "* Easy integration of extensions (Cython, C, Fortran)\n",
+ "* Easy integration of extensions (Cython, C, C++, Fortran)\n",
"* For development: use `pip install -e ./ --user` (development install, always uses the modules from the current folder)\n",
- "* Facilitates sharing with others\n",
+ "* Facilitates sharing of the code with others, potentially via PyPI\n",
"\n",
"$\\to$ recommended for all projects!"
]
},
+ {
+ "cell_type": "markdown",
+ "metadata": {
+ "slideshow": {
+ "slide_type": "subslide"
+ }
+ },
+ "source": [
+ "### Components of a full-fledged software package\n",
+ "\n",
+ "* source code\n",
+ "* installation routines (`setup.py`)\n",
+ "* user documentation - how to use the package\n",
+ "* develper documentation - how to develop code for the package\n",
+ "* software tests\n",
+ "* commonly expected text files to help people get information quickly (e.g. on public repositories)\n",
+ " * `README`\n",
+ " * `LICENSE`\n",
+ " * `CONTRIBUTING`\n",
+ " * `CHANGELOG`"
+ ]
+ },
{
"cell_type": "markdown",
"metadata": {
@@ -152,10 +176,15 @@
},
"source": [
"## Documentation\n",
+ "### Comments\n",
+ "\n",
"* *Comments* begin with a hash sign and extend until the end of the line\n",
- "* Put (single line) comments where they might help to clarify your code\n",
- "* *Docstrings* are used to describe the purpose of a module, function, or class. They are enclosed in triple quotes and may extend over multiple lines.\n",
- "* NumPy-style docstrings have proven useful. See the example below."
+ " ```python\n",
+ " # TODO initialize list with default values\n",
+ " a = []\n",
+ " ```\n",
+ "* *Comments* are programmer's notes, for user documentation use docstrings (see below)\n",
+ "* Put (single line) comments where they might help to clarify your code, remind about TODOs, etc. -- but avoid trivial comments"
]
},
{
@@ -167,9 +196,12 @@
},
"source": [
"### Docstrings\n",
- "* Very useful to understand one's own code after 2 years\n",
- "* Also useful when collaborating with others\n",
- "* Can be used for automated generation of documentation"
+ "\n",
+ "* *Docstrings* are used to describe the purpose of a module, function, or class. They are enclosed in triple quotes and may extend over multiple lines.\n",
+ "* Often helpful to understand one's own code after 2 years\n",
+ "* Essential when collaborating with others and publishing code\n",
+ "* Displayed when using the `help()` builtin of Python\n",
+ "* Can be used for automated generation of documentation (e.g. using Sphinx)"
]
},
{
@@ -198,7 +230,9 @@
},
"source": [
"### NumPy-style docstrings\n",
- "* Good for documenting purpose of input variables and result"
+ "\n",
+ "* NumPy-style docstrings are widely used in scientific Python programming\n",
+ "* Covers datatypes and purpose of input variables and return value"
]
},
{
@@ -245,7 +279,7 @@
"* Python documentation generator, de-facto standard\n",
"* Create documentation in HTML, PDF, and other formats from\n",
" * reStructuredText (`.rst`) files\n",
- " * **Can use docstrings in source files**\n",
+ " * docstrings in source files\n",
"* Automated generation of documentation is possible via web services such as _GitHub_ and _Read the Docs_\n",
"\n",
"http://www.sphinx-doc.org/en/master/"
@@ -259,15 +293,21 @@
}
},
"source": [
- "### Sphinx example\n",
+ "### Sphinx\n",
+ "\n",
+ "Steps\n",
+ "\n",
"* Use `sphinx-quickstart` to create default files for the documentation\n",
- "* Adapt `conf.py` to your needs\n",
+ "* Adapt `conf.py` to your needs, enable useful Sphinx addons such as\n",
" * `sphinx.ext.autodoc`: include docstrings into documentation\n",
" * `sphinx.ext.napoleon`: support for NumPy-style docstrings\n",
"* Edit `index.rst`, potentially create other rst files\n",
"* Run `make html` to generate the HTML documentation\n",
+ "\n",
+ "Example\n",
+ "\n",
"* Can be integrated into `setup.py` (run ` python setup.py build_sphinx`)\n",
- "* See the directory `setuptools/hello_world_with_sphinx` for an example"
+ "* See the directory `setuptools/sphinx-doc` for an example"
]
},
{
@@ -285,7 +325,7 @@
" * Integration tests\n",
" * test the interplay of units, up to the complete application\n",
"* `unittest`, `pytest`, and `nose` are popular Python modules for testing\n",
- "* \"continuous integration\" allows to run tests automatically at each code commit, e.g. via GitLab-CI runner on a local/virtual machine"
+ "* \"continuous integration\" allows to run tests automatically at each code commit, e.g. via GitLab-CI"
]
},
{
@@ -324,7 +364,7 @@
},
"source": [
"### pytest example with setup.py\n",
- "$\\to$ See the directory `setuptools/hello_world_with_tests` for an example on how to integrate tests into `setup.py`"
+ "$\\to$ See the directory `setuptools/py-test` for an example on how to integrate tests into `setup.py`"
]
},
{
@@ -336,16 +376,18 @@
},
"source": [
"## Version Control Systems, GIT\n",
- "* Use version control for _any_ project\n",
+ "\n",
+ "* use version control for _any_ project\n",
" * Distributed development of large projects\n",
" * Small local single-person projects\n",
" * Useful during performance optimization\n",
"* `git` is the tool of choice today \n",
- "* Good tutorial: https://git-scm.com/docs/gittutorial\n",
- "* MPCDF GitLab provides web-based repository services for collaboration\n",
+ "* good tutorial: https://git-scm.com/docs/gittutorial\n",
+ "* [MPCDF GitLab](https://gitlab.mpcdf.mpg.de/) provides web-based repository services for collaboration\n",
" * git repository\n",
- " * Issue tracker\n",
- " * Wiki"
+ " * issue tracker\n",
+ " * wiki\n",
+ " * CI option for automated tests"
]
},
{
@@ -382,10 +424,10 @@
"## PyPI, the Python Package Index\n",
"* PyPI is the online software repository for Python\n",
"* https://pypi.python.org/pypi\n",
- "* Contains nearly 140.000 packages (May 2018)\n",
- "* Anybody may upload packages after registration\n",
+ "* Contains nearly 330.000 packages (Oct 2021)\n",
"* Zip files, tar balls, wheel archives are accepted \n",
- " (typically generated locally by `setup.py` first)"
+ " (typically generated locally by `setup.py` first)\n",
+ "* Anybody may upload packages after registration"
]
},
{
@@ -397,7 +439,8 @@
},
"source": [
"### PyPI (cont'd), pip\n",
- "* `pip` is used to download and install packages \n",
+ "\n",
+ "* `pip` is used to download and install packages from PyPI \n",
" `pip install --user PACKAGE`\n",
"* `pip uninstall PACKAGE`\n",
"* Software dependencies are resolved automatically"
@@ -435,7 +478,7 @@
"name": "python",
"nbconvert_exporter": "python",
"pygments_lexer": "ipython3",
- "version": "3.8.3"
+ "version": "3.8.8"
}
},
"nbformat": 4,
--
GitLab