Merge pull request #8 from scientificcomputing/modules-packages

Modules, packages and other typos
scientificcomputing · Nov 16, 2023 · 14ed555 · 14ed555
2 parents 7e5f577 + 511c79e
commit 14ed555
Show file tree

Hide file tree

Showing 7 changed files with 262 additions and 102 deletions.
diff --git a/README.md b/README.md
@@ -7,8 +7,8 @@ The agenda is as follows
 
 - Code and Data repositories [Slides](https://scientificcomputing.github.io/seminar-23-11-2023/repo-slides.html) [Book](https://scientificcomputing.github.io/seminar-23-11-2023/docs/repo.html)
 - Reproducible environments [Slides](https://scientificcomputing.github.io/seminar-23-11-2023/environments-slides.html) [Book](https://scientificcomputing.github.io/seminar-23-11-2023/docs/environments.html)
-- Documentation [Slides](https://scientificcomputing.github.io/seminar-23-11-2023/documentation-slides.html) [Book](https://scientificcomputing.github.io/seminar-23-11-2023/docs/documentation.html)
 - Linters, formatters and continuous integration [Slides](https://scientificcomputing.github.io/seminar-23-11-2023/testing-slides.html) [Book](https://scientificcomputing.github.io/seminar-23-11-2023/docs/testing.html)
+- Documentation [Slides](https://scientificcomputing.github.io/seminar-23-11-2023/documentation-slides.html) [Book](https://scientificcomputing.github.io/seminar-23-11-2023/docs/documentation.html)
 - Example paper with code [Slides](https://scientificcomputing.github.io/seminar-23-11-2023/paper-slides.html) [Book](https://scientificcomputing.github.io/seminar-23-11-2023/docs/paper.html)
 - Packaging and Distribution (if time) [Slides](https://scientificcomputing.github.io/seminar-23-11-2023/distribution-slides.html) [Book](https://scientificcomputing.github.io/seminar-23-11-2023/docs/distribution.html)
 

diff --git a/cspell.json b/cspell.json
@@ -19,8 +19,11 @@
         "Finsberg",
         "ipython",
         "isort",
+        "itertools",
+        "itools",
         "Jørgen",
         "jupytext",
+        "licence",
         "linkify",
         "marp",
         "matplotlib",
@@ -34,6 +37,7 @@
         "pyproject",
         "pytest",
         "pyupgrade",
+        "Ragan",
         "repr",
         "scientificcomputing",
         "scipy",

diff --git a/docs/distribution.md b/docs/distribution.md
@@ -29,3 +29,34 @@ Henrik Finsberg and Jørgen Dokken
     - Creating a GitHub action to publish a new docker image to the GitHub registry whenever you make a new release
 - Licensing
     - Which license to put on your code and why you should use a permissive license
+
+---
+
+## Creating a package
+
+- A set of modules can be collected in a package
+
+- A package is organized as module files in a directory tree
+
+- Each subdirectory must have a __init__.py file (can be empty)
+
+```
+examples/my-package
+├── LICENSE
+├── pyproject.toml
+├── README.md
+├── src
+│   └── pkg
+│       ├── analysis.py
+│       ├── __init__.py
+│       └── printing
+│           ├── __init__.py
+│           └── printing.py
+└── test
+    ├── test_analysis.py
+    └── test_printing.py
+```
+
+---
+
+## Installing a package
diff --git a/docs/documentation.md b/docs/documentation.md
@@ -18,25 +18,13 @@ Best Practices in Modern Software Development: 23.11.23
 Henrik Finsberg and Jørgen Dokken
 
 
----
-
-## Agenda
-
-- Why documentation?
-- Writing docstrings and generating API documentation
-    - numpy vs Google style
-- Writing documentation using Jupyter-Book
-- Hosting documentation on GitHub pages
-
-
 ---
 
 ## What is documentation?
 
 * Background and motivation
     - What do you try to solve?
-* Instructions on how to install the software
-    - Installation instructions
+* Instructions on how to install the software and necessary dependencies
 * Instructions on how to use the software
     - Tutorials / demos
     - API documentation
@@ -53,6 +41,31 @@ Henrik Finsberg and Jørgen Dokken
 
 ---
 
+## The README file
+
+- The first documentation a user reads is the README file
+- Should include
+  - Title of the project
+  - Description of the project
+  - Installation instructions
+  - How to get started
+
+---
+
+- Could include
+  - Badges
+  - Information about how to contribute
+  - License information
+  - Credits
+  - Example
+  - How to cite
+  - Screenshots / figures
+- https://readme.so
+
+
+---
+
+
 ## Using JupyterBook to create documentation
 
 - [JupyterBook](https://jupyterbook.org/en/stable/intro.html) is a powerful framework for writing documentation
@@ -235,14 +248,78 @@ parse:
 
 ## Publishing the book to GitHub pages
 
-- Create a new file `.github/workflows/build_docs.yml`
+- Create a new file `.github/workflows/build_docs.yml` which contains a workflow for building the docs
+- Also remember to go to your [repository settings on GitHub](https://docs.github.com/en/pages/getting-started-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site#publishing-with-a-custom-github-actions-workflow) to allow for GitHub pages, see
+
+---
 
 ```yaml
 # Simple workflow for deploying static content to GitHub Pages
-name: Deploy static content to Pages
+name: Build docs
+
+on:
+  workflow_dispatch:
+  workflow_call:
+  pull_request:
+    branches:
+      - main
 
-on: [push]
+jobs:
+  build_docs:
+    runs-on: ubuntu-22.04
+    env:
+      PYTHON_VERSION: "3.10"
+      PUBLISH_DIR: ./_build/html
+
+    steps:
+      # checkout the repository
+      - uses: actions/checkout@v4
+
+      # setup Python
+      - name: Install Python ${{ env.PYTHON_VERSION }}
+        uses: actions/setup-python@v4
+        with:
+          python-version: ${{ env.PYTHON_VERSION }}
+
+      # preserve pip cache to speed up installation
+      - name: Cache pip
+        uses: actions/cache@v3
+        with:
+          path: ~/.cache/pip
+          # Look to see if there is a cache hit for the corresponding requirements file
+          key: ${{ runner.os }}-pip-${{ hashFiles('*requirements-docs.txt') }}
+          restore-keys: |
+            ${{ runner.os }}-pip-
+      - name: Install Python dependencies
+        run: |
+          python3 -m pip install --upgrade pip
+          python3 -m pip install -r requirements-docs.txt
 
+      - name: Build docs
+        run: python3 -m jupyter book build .
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          name: documentation
+          path: ${{ env.PUBLISH_DIR }}
+          if-no-files-found: error
+```
+
+---
+
+## Publishing the book to GitHub pages
+
+- Create a new file `.github/workflows/publish_docs.yml` which contains a workflow for publishing the docs to github pages
+
+---
+
+```yaml
+name: Github Pages
+
+on:
+  push:
+    branches: [main]  # Only run on push to main
 
 # Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
 permissions:
@@ -255,49 +332,37 @@ concurrency:
   group: "pages"
   cancel-in-progress: true
 
-env:
-  # Directory that will be published on github pages
-  PUBLISH_DIR: ./_build/html
-
 jobs:
+  build-docs:
+    uses: ./.github/workflows/build_docs.yml
 
-  build:
-    runs-on: ubuntu-22.04
-
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v4
-
-      - name: Install dependencies
-        run: |
-          python3 -m pip install jupyter-book jupytext
-
-      - name: Build docs
-        run: jupyter book build .
-
-      - name: Upload artifact
-        uses: actions/upload-pages-artifact@v2
-        with:
-          path: ${{ env.PUBLISH_DIR }}
-
-  # Single deploy job since we're just deploying
   deploy:
-    if: github.ref == 'refs/heads/main'
-    needs: build
+    needs: [build-docs]
+
     environment:
       name: github-pages
       url: ${{ steps.deployment.outputs.page_url }}
 
     runs-on: ubuntu-latest
-
     steps:
+      - name: Download docs artifact
+        # docs artifact is uploaded by build-docs job
+        uses: actions/download-artifact@v3
+        with:
+          name: documentation
+          path: "./public"
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v2
+        with:
+          path: "./public"
+
       - name: Checkout
         uses: actions/checkout@v4
 
       - name: Setup Pages
         uses: actions/configure-pages@v3
 
-
       - name: Deploy to GitHub Pages
         id: deployment
         uses: actions/deploy-pages@v2

diff --git a/docs/environments.md b/docs/environments.md
@@ -15,18 +15,57 @@ marp: true
 # Reproducible environments
 Best Practices in Modern Software Development: 23.11.23
 
-Henrik Finsberg and Jørgen Dokken
+Henrik Finsberg, Jørgen Dokken and Benjamin Ragan-Kelly
 
 ---
 
-## Agenda
+- A module is a file consisting of Python code
+- A package is a hierarchical file directory structure that consists of modules and sub-packages
 
-- What is a development environment
-- Virtual environments in python
-    - pinning dependencies with `pip-tools`
-    - pyproject.toml
-- Conda
-- Docker
+![bg fit right](https://uio-in3110.github.io/_images/python_structure_options.svg)
+
+---
+
+## Using modules
+
+```python
+import itertools
+# Access function from the module
+itertools.product
+
+# Alias
+import itertools as itools
+itools.product
+
+# The following is considered a bad practice
+from itertools import *
+# Easy to shadow existing variables (also hard for IDEs)
+```
+
+
+---
+
+## Using packages
+
+```python
+from scipy.optimize import minimize
+#      ^      ^               ^
+#      |      |               |
+#   Package   |               |
+#           Module            |
+#                          Function
+```
+
+---
+
+## How does python know which modules and packages that are available?
+
+```python
+import sys
+
+# Notice the order
+sys.path
+```
 
 ---
 
@@ -116,8 +155,6 @@ deactivate
 
 ## Example `pyproject.toml`
 
-FIXME: No we need build-system?
-
 ```toml
 [build-system]  # Setuptools + editable install
 requires = ["setuptools>=61.2"]
@@ -229,17 +266,16 @@ pip-compile --extra=dev --output-file=requirements-dev.txt pyproject.toml
 
 ---
 
+Demo
+
+---
 
 ## Conda
 
 TBW
 
 ---
 
-Demo
-
----
-
 ## Docker
 
 [Docker](https://www.docker.com/get-started/) is a platform that packages an application and all its dependencies together in the form of containers.
@@ -373,5 +409,3 @@ The simplest way to ensure that users than exactly reproduce your environment is
 Therefore you should always publish a docker image containing the exact dependencies for reproducing the results
 
 The templates contains a workflow for building docker images using GitHub actions for every new tag
-
----