Demonstration: How to use these tools¶
Just like in the previous section, we'll try making a demo. We're still going to be using a notebook, and usually you'd do some of these commands in a terminal, but it'll work for our purposes. You might also want to check out the next section which bundles these commands into a Makefile.
(Note because we're executing this in a notebook, sometimes we need to use the '!' symbol to execute shell commands.)
In [1]:
# Note I'm loading the autoreload extension so that we can load functions from two git branches
%load_ext autoreload
%autoreload 2
In [2]:
mkdir demo
In [3]:
cd demo
/Users/ch/repos/astronomy_workflow/docs/notebooks/3.0-building/demo
Let's look at the python versions I have installed
In [4]:
! pyenv versions
system * 3.8.7 (set by PYENV_VERSION environment variable) 3.8.7/envs/tess-asteroids 3.9.1 3.9.1/envs/tess-backdrop tess-asteroids tess-backdrop
I have a few, and I have some special virtual environments with names. I think we'll use the 3.8.0 python version for this project. Let's make a virtual environment and call it demo
In [7]:
! pyenv virtualenv 3.8.7 demo
created virtual environment CPython3.8.7.final.0-64 in 313ms
creator CPython3Posix(dest=/Users/ch/.pyenv/versions/3.8.7/envs/demo, clear=False, no_vcs_ignore=False, global=False)
seeder FromAppData(download=False, pip=bundle, setuptools=bundle, wheel=bundle, via=copy, app_data_dir=/Users/ch/Library/Application Support/virtualenv)
added seed packages: pip==21.0.1, setuptools==56.2.0, wheel==0.36.2
activators BashActivator,CShellActivator,FishActivator,PowerShellActivator,PythonActivator,XonshActivator
Looking in links: /var/folders/pz/0x8sm5hj44q6gx0qg_6n00xw0000gn/T/tmpyjn36ke2
Requirement already satisfied: setuptools in /Users/ch/.pyenv/versions/3.8.7/envs/demo/lib/python3.8/site-packages (56.2.0)
Requirement already satisfied: pip in /Users/ch/.pyenv/versions/3.8.7/envs/demo/lib/python3.8/site-packages (21.0.1)
In [8]:
! pyenv versions
system * 3.8.7 (set by PYENV_VERSION environment variable) 3.8.7/envs/demo 3.8.7/envs/tess-asteroids 3.9.1 3.9.1/envs/tess-backdrop demo tess-asteroids tess-backdrop
Great, demo is now listed in my versions. Let's set the local version to demo
In [9]:
! pyenv local demo
In [10]:
! pyenv version
3.8.7 (set by PYENV_VERSION environment variable)
In [11]:
! pyenv which pip
/Users/ch/.pyenv/versions/3.8.7/bin/pip
This is a new virtual environment, so we won't have anything installed, let's install poetry
In [12]:
! pip install -U poetry pip;
Requirement already satisfied: poetry in /Users/ch/.pyenv/versions/3.8.7/lib/python3.8/site-packages (1.1.6) Requirement already satisfied: pip in /Users/ch/.pyenv/versions/3.8.7/lib/python3.8/site-packages (21.1.2) Requirement already satisfied: requests-toolbelt<0.10.0,>=0.9.1 in /Users/ch/.pyenv/versions/3.8.7/lib/python3.8/site-packages (from poetry) (0.9.1) Requirement already satisfied: shellingham<2.0,>=1.1 in /Users/ch/.pyenv/versions/3.8.7/lib/python3.8/site-packages (from poetry) (1.4.0) Requirement already satisfied: tomlkit<1.0.0,>=0.7.0 in /Users/ch/.pyenv/versions/3.8.7/lib/python3.8/site-packages (from poetry) (0.7.0) Requirement already satisfied: pexpect<5.0.0,>=4.7.0 in /Users/ch/.pyenv/versions/3.8.7/lib/python3.8/site-packages (from poetry) (4.8.0) Requirement already satisfied: cleo<0.9.0,>=0.8.1 in /Users/ch/.pyenv/versions/3.8.7/lib/python3.8/site-packages (from poetry) (0.8.1) Requirement already satisfied: cachecontrol[filecache]<0.13.0,>=0.12.4 in /Users/ch/.pyenv/versions/3.8.7/lib/python3.8/site-packages (from poetry) (0.12.6) Requirement already satisfied: requests<3.0,>=2.18 in /Users/ch/.pyenv/versions/3.8.7/lib/python3.8/site-packages (from poetry) (2.25.1) Requirement already satisfied: pkginfo<2.0,>=1.4 in /Users/ch/.pyenv/versions/3.8.7/lib/python3.8/site-packages (from poetry) (1.7.0) Requirement already satisfied: crashtest<0.4.0,>=0.3.0 in /Users/ch/.pyenv/versions/3.8.7/lib/python3.8/site-packages (from poetry) (0.3.1) Requirement already satisfied: poetry-core<1.1.0,>=1.0.3 in /Users/ch/.pyenv/versions/3.8.7/lib/python3.8/site-packages (from poetry) (1.0.3) Requirement already satisfied: packaging<21.0,>=20.4 in /Users/ch/.pyenv/versions/3.8.7/lib/python3.8/site-packages (from poetry) (20.9) Requirement already satisfied: virtualenv<21.0.0,>=20.0.26 in /Users/ch/.pyenv/versions/3.8.7/lib/python3.8/site-packages (from poetry) (20.4.4) Requirement already satisfied: clikit<0.7.0,>=0.6.2 in /Users/ch/.pyenv/versions/3.8.7/lib/python3.8/site-packages (from poetry) (0.6.2) Requirement already satisfied: html5lib<2.0,>=1.0 in /Users/ch/.pyenv/versions/3.8.7/lib/python3.8/site-packages (from poetry) (1.1) Requirement already satisfied: cachy<0.4.0,>=0.3.0 in /Users/ch/.pyenv/versions/3.8.7/lib/python3.8/site-packages (from poetry) (0.3.0) Requirement already satisfied: keyring<22.0.0,>=21.2.0 in /Users/ch/.pyenv/versions/3.8.7/lib/python3.8/site-packages (from poetry) (21.8.0) Requirement already satisfied: msgpack>=0.5.2 in /Users/ch/.pyenv/versions/3.8.7/lib/python3.8/site-packages (from cachecontrol[filecache]<0.13.0,>=0.12.4->poetry) (1.0.2) Requirement already satisfied: lockfile>=0.9 in /Users/ch/.pyenv/versions/3.8.7/lib/python3.8/site-packages (from cachecontrol[filecache]<0.13.0,>=0.12.4->poetry) (0.12.2) Requirement already satisfied: pastel<0.3.0,>=0.2.0 in /Users/ch/.pyenv/versions/3.8.7/lib/python3.8/site-packages (from clikit<0.7.0,>=0.6.2->poetry) (0.2.1) Requirement already satisfied: pylev<2.0,>=1.3 in /Users/ch/.pyenv/versions/3.8.7/lib/python3.8/site-packages (from clikit<0.7.0,>=0.6.2->poetry) (1.3.0) Requirement already satisfied: six>=1.9 in /Users/ch/.pyenv/versions/3.8.7/lib/python3.8/site-packages (from html5lib<2.0,>=1.0->poetry) (1.15.0) Requirement already satisfied: webencodings in /Users/ch/.pyenv/versions/3.8.7/lib/python3.8/site-packages (from html5lib<2.0,>=1.0->poetry) (0.5.1) Requirement already satisfied: pyparsing>=2.0.2 in /Users/ch/.pyenv/versions/3.8.7/lib/python3.8/site-packages (from packaging<21.0,>=20.4->poetry) (2.4.7) Requirement already satisfied: ptyprocess>=0.5 in /Users/ch/.pyenv/versions/3.8.7/lib/python3.8/site-packages (from pexpect<5.0.0,>=4.7.0->poetry) (0.7.0) Requirement already satisfied: urllib3<1.27,>=1.21.1 in /Users/ch/.pyenv/versions/3.8.7/lib/python3.8/site-packages (from requests<3.0,>=2.18->poetry) (1.26.4) Requirement already satisfied: certifi>=2017.4.17 in /Users/ch/.pyenv/versions/3.8.7/lib/python3.8/site-packages (from requests<3.0,>=2.18->poetry) (2020.12.5) Requirement already satisfied: idna<3,>=2.5 in /Users/ch/.pyenv/versions/3.8.7/lib/python3.8/site-packages (from requests<3.0,>=2.18->poetry) (2.10) Requirement already satisfied: chardet<5,>=3.0.2 in /Users/ch/.pyenv/versions/3.8.7/lib/python3.8/site-packages (from requests<3.0,>=2.18->poetry) (4.0.0) Requirement already satisfied: filelock<4,>=3.0.0 in /Users/ch/.pyenv/versions/3.8.7/lib/python3.8/site-packages (from virtualenv<21.0.0,>=20.0.26->poetry) (3.0.12) Requirement already satisfied: distlib<1,>=0.3.1 in /Users/ch/.pyenv/versions/3.8.7/lib/python3.8/site-packages (from virtualenv<21.0.0,>=20.0.26->poetry) (0.3.1) Requirement already satisfied: appdirs<2,>=1.4.3 in /Users/ch/.pyenv/versions/3.8.7/lib/python3.8/site-packages (from virtualenv<21.0.0,>=20.0.26->poetry) (1.4.4)
Beautiful. Now we can initialize a new poetry project called demo with the new command. We use --src because that makes the directory structure that I personally like.
In [13]:
! poetry new --src demo
Created package demo in demo
In [14]:
cd demo
/Users/ch/repos/astronomy_workflow/docs/notebooks/3.0-building/demo/demo
In [15]:
ls
README.rst pyproject.toml src/ tests/
Now we can see that poetry has made a README, a pyproject.toml file, and a directory for tests and code. Let's add some dependencies.
In [18]:
! poetry add numpy
Using version ^1.20.3 for numpy Updating dependencies Resolving dependencies... (0.2s) Writing lock file Package operations: 1 install, 0 updates, 0 removals • Installing numpy (1.20.3): Pending... • Installing numpy (1.20.3): Installing... • Installing numpy (1.20.3)
This looks great, we've installed numpy as a dependency of our tool. If we like, we can also install development dependencies.
In [17]:
# I've run this twice, the output is very long!
! poetry add -D jupyterlab
The following packages are already present in the pyproject.toml and will be skipped:
• jupyterlab
If you want to update it to the latest compatible version, you can use `poetry update package`.
If you prefer to upgrade it to the latest available version, you can use `poetry add package@latest`.
Nothing to add.
Note that adding in the -D flag makes sure we're only adding this tool in development mode. We don't want users to be forced to add jupyterlab just to install our tool! If we want to use the mkdocs tool to make our docs, we might also want to install mkdocs as a development dependency.
In [20]:
# These install mkdocs, the mkdocstrings add-on for parsing doc strings and the material theme
! poetry add -D mkdocs mkdocstrings mkdocs-material
# This installs the numpy-style for pytkdocs so mkdocs can parse our numpy-doc style doc strings
! poetry add -D pytkdocs -E numpy-style
Using version ^1.2.1 for mkdocs Using version ^0.15.2 for mkdocstrings Using version ^7.1.8 for mkdocs-material Updating dependencies Resolving dependencies... (2.5s)Resolving dependencies... (0.8s)Resolving dependencies... (2.3s) Writing lock file Package operations: 15 installs, 0 updates, 0 removals • Installing pyyaml (5.4.1): Pending... • Installing zipp (3.4.1): Pending... • Installing zipp (3.4.1): Pending... • Installing pyyaml (5.4.1): Installing... • Installing zipp (3.4.1): Pending... • Installing zipp (3.4.1): Installing... • Installing zipp (3.4.1) • Installing zipp (3.4.1) • Installing pyyaml (5.4.1) • Installing zipp (3.4.1) • Installing click (8.0.1): Pending... • Installing ghp-import (2.0.1): Pending... • Installing importlib-metadata (4.5.0): Pending... • Installing markdown (3.3.4): Pending... • Installing mergedeep (1.3.4): Pending... • Installing pyyaml-env-tag (0.1): Pending... • Installing watchdog (2.1.2): Pending... • Installing ghp-import (2.0.1): Pending... • Installing importlib-metadata (4.5.0): Pending... • Installing markdown (3.3.4): Pending... • Installing mergedeep (1.3.4): Pending... • Installing pyyaml-env-tag (0.1): Pending... • Installing watchdog (2.1.2): Pending... • Installing click (8.0.1): Installing... • Installing ghp-import (2.0.1): Pending... • Installing importlib-metadata (4.5.0): Pending... • Installing markdown (3.3.4): Pending... • Installing mergedeep (1.3.4): Pending... • Installing pyyaml-env-tag (0.1): Pending... • Installing watchdog (2.1.2): Pending... • Installing importlib-metadata (4.5.0): Pending... • Installing markdown (3.3.4): Pending... • Installing mergedeep (1.3.4): Pending... • Installing pyyaml-env-tag (0.1): Pending... • Installing watchdog (2.1.2): Pending... • Installing ghp-import (2.0.1): Downloading... 0% • Installing importlib-metadata (4.5.0): Pending... • Installing markdown (3.3.4): Pending... • Installing mergedeep (1.3.4): Pending... • Installing pyyaml-env-tag (0.1): Pending... • Installing watchdog (2.1.2): Pending... • Installing pyyaml-env-tag (0.1): Pending... • Installing watchdog (2.1.2): Pending... • Installing mergedeep (1.3.4): Downloading... 0% • Installing pyyaml-env-tag (0.1): Pending... • Installing watchdog (2.1.2): Pending... • Installing markdown (3.3.4): Pending... • Installing mergedeep (1.3.4): Downloading... 0% • Installing pyyaml-env-tag (0.1): Pending... • Installing watchdog (2.1.2): Pending... • Installing importlib-metadata (4.5.0): Downloading... 0% • Installing markdown (3.3.4): Pending... • Installing mergedeep (1.3.4): Downloading... 0% • Installing pyyaml-env-tag (0.1): Pending... • Installing watchdog (2.1.2): Pending... • Installing watchdog (2.1.2): Pending... • Installing pyyaml-env-tag (0.1): Downloading... 0% • Installing watchdog (2.1.2): Pending... • Installing importlib-metadata (4.5.0): Downloading... 0% • Installing markdown (3.3.4): Pending... • Installing mergedeep (1.3.4): Downloading... 0% • Installing pyyaml-env-tag (0.1): Downloading... 0% • Installing watchdog (2.1.2): Pending... • Installing ghp-import (2.0.1): Downloading... 100% • Installing importlib-metadata (4.5.0): Downloading... 0% • Installing markdown (3.3.4): Pending... • Installing mergedeep (1.3.4): Downloading... 0% • Installing pyyaml-env-tag (0.1): Downloading... 0% • Installing watchdog (2.1.2): Pending... • Installing watchdog (2.1.2): Downloading... 0% • Installing importlib-metadata (4.5.0): Downloading... 0% • Installing markdown (3.3.4): Pending... • Installing mergedeep (1.3.4): Downloading... 0% • Installing pyyaml-env-tag (0.1): Downloading... 0% • Installing watchdog (2.1.2): Downloading... 0% • Installing ghp-import (2.0.1): Downloading... 100% • Installing importlib-metadata (4.5.0): Downloading... 0% • Installing markdown (3.3.4): Pending... • Installing mergedeep (1.3.4): Downloading... 0% • Installing pyyaml-env-tag (0.1): Downloading... 0% • Installing watchdog (2.1.2): Downloading... 0% • Installing importlib-metadata (4.5.0): Downloading... 0% • Installing markdown (3.3.4): Pending... • Installing mergedeep (1.3.4): Downloading... 0% • Installing pyyaml-env-tag (0.1): Downloading... 0% • Installing watchdog (2.1.2): Downloading... 0% • Installing ghp-import (2.0.1): Installing... • Installing importlib-metadata (4.5.0): Downloading... 0% • Installing markdown (3.3.4): Pending... • Installing mergedeep (1.3.4): Downloading... 0% • Installing pyyaml-env-tag (0.1): Downloading... 0% • Installing watchdog (2.1.2): Downloading... 0% • Installing pyyaml-env-tag (0.1): Downloading... 0% • Installing watchdog (2.1.2): Downloading... 0% • Installing mergedeep (1.3.4): Downloading... 100% • Installing pyyaml-env-tag (0.1): Downloading... 0% • Installing watchdog (2.1.2): Downloading... 0% • Installing watchdog (2.1.2): Downloading... 0% • Installing pyyaml-env-tag (0.1): Downloading... 100% • Installing watchdog (2.1.2): Downloading... 0% • Installing watchdog (2.1.2): Downloading... 0% • Installing pyyaml-env-tag (0.1): Downloading... 100% • Installing watchdog (2.1.2): Downloading... 0% • Installing pyyaml-env-tag (0.1): Downloading... 100% • Installing watchdog (2.1.2): Downloading... 0% • Installing mergedeep (1.3.4): Downloading... 100% • Installing pyyaml-env-tag (0.1): Downloading... 100% • Installing watchdog (2.1.2): Downloading... 0% • Installing pyyaml-env-tag (0.1): Downloading... 100% • Installing watchdog (2.1.2): Downloading... 0% • Installing mergedeep (1.3.4): Installing... • Installing pyyaml-env-tag (0.1): Downloading... 100% • Installing watchdog (2.1.2): Downloading... 0% • Installing markdown (3.3.4): Pending... • Installing mergedeep (1.3.4): Installing... • Installing pyyaml-env-tag (0.1): Downloading... 100% • Installing watchdog (2.1.2): Downloading... 0% • Installing importlib-metadata (4.5.0): Downloading... 100% • Installing markdown (3.3.4): Pending... • Installing mergedeep (1.3.4): Installing... • Installing pyyaml-env-tag (0.1): Downloading... 100% • Installing watchdog (2.1.2): Downloading... 0% • Installing markdown (3.3.4): Pending... • Installing mergedeep (1.3.4): Installing... • Installing pyyaml-env-tag (0.1): Downloading... 100% • Installing watchdog (2.1.2): Downloading... 0% • Installing importlib-metadata (4.5.0): Downloading... 100% • Installing markdown (3.3.4): Pending... • Installing mergedeep (1.3.4): Installing... • Installing pyyaml-env-tag (0.1): Downloading... 100% • Installing watchdog (2.1.2): Downloading... 0% • Installing watchdog (2.1.2): Downloading... 0% • Installing pyyaml-env-tag (0.1): Installing... • Installing watchdog (2.1.2): Downloading... 0% • Installing markdown (3.3.4): Pending... • Installing mergedeep (1.3.4): Installing... • Installing pyyaml-env-tag (0.1): Installing... • Installing watchdog (2.1.2): Downloading... 0% • Installing importlib-metadata (4.5.0): Installing... • Installing markdown (3.3.4): Pending... • Installing mergedeep (1.3.4): Installing... • Installing pyyaml-env-tag (0.1): Installing... • Installing watchdog (2.1.2): Downloading... 0% • Installing watchdog (2.1.2): Downloading... 100% • Installing watchdog (2.1.2): Downloading... 100% • Installing watchdog (2.1.2): Installing... • Installing mergedeep (1.3.4): Installing... • Installing pyyaml-env-tag (0.1): Installing... • Installing watchdog (2.1.2): Installing... • Installing markdown (3.3.4): Installing... • Installing mergedeep (1.3.4): Installing... • Installing pyyaml-env-tag (0.1): Installing... • Installing watchdog (2.1.2): Installing... • Installing ghp-import (2.0.1): Installing... • Installing importlib-metadata (4.5.0): Installing... • Installing markdown (3.3.4): Installing... • Installing mergedeep (1.3.4): Installing... • Installing pyyaml-env-tag (0.1): Installing... • Installing watchdog (2.1.2): Installing... • Installing click (8.0.1) • Installing ghp-import (2.0.1): Installing... • Installing importlib-metadata (4.5.0): Installing... • Installing markdown (3.3.4): Installing... • Installing mergedeep (1.3.4): Installing... • Installing pyyaml-env-tag (0.1): Installing... • Installing watchdog (2.1.2): Installing... • Installing pyyaml-env-tag (0.1): Installing... • Installing watchdog (2.1.2): Installing... • Installing mergedeep (1.3.4) • Installing pyyaml-env-tag (0.1): Installing... • Installing watchdog (2.1.2): Installing... • Installing markdown (3.3.4): Installing... • Installing mergedeep (1.3.4) • Installing pyyaml-env-tag (0.1): Installing... • Installing watchdog (2.1.2): Installing... • Installing importlib-metadata (4.5.0) • Installing markdown (3.3.4): Installing... • Installing mergedeep (1.3.4) • Installing pyyaml-env-tag (0.1): Installing... • Installing watchdog (2.1.2): Installing... • Installing watchdog (2.1.2): Installing... • Installing pyyaml-env-tag (0.1) • Installing watchdog (2.1.2): Installing... • Installing watchdog (2.1.2) • Installing mergedeep (1.3.4) • Installing pyyaml-env-tag (0.1) • Installing watchdog (2.1.2) • Installing markdown (3.3.4) • Installing mergedeep (1.3.4) • Installing pyyaml-env-tag (0.1) • Installing watchdog (2.1.2) • Installing importlib-metadata (4.5.0) • Installing markdown (3.3.4) • Installing mergedeep (1.3.4) • Installing pyyaml-env-tag (0.1) • Installing watchdog (2.1.2) • Installing ghp-import (2.0.1) • Installing importlib-metadata (4.5.0) • Installing markdown (3.3.4) • Installing mergedeep (1.3.4) • Installing pyyaml-env-tag (0.1) • Installing watchdog (2.1.2) • Installing mkdocs (1.2.1): Pending... • Installing mkdocs (1.2.1): Downloading... 0% • Installing mkdocs (1.2.1): Downloading... 10% • Installing mkdocs (1.2.1): Downloading... 40% • Installing mkdocs (1.2.1): Downloading... 70% • Installing mkdocs (1.2.1): Downloading... 100% • Installing mkdocs (1.2.1): Downloading... 100% • Installing mkdocs (1.2.1): Installing... • Installing mkdocs (1.2.1) • Installing mkdocs-autorefs (0.2.1): Pending... • Installing mkdocs-material-extensions (1.0.1): Pending... • Installing pymdown-extensions (8.2): Pending... • Installing pymdown-extensions (8.2): Pending... • Installing mkdocs-material-extensions (1.0.1): Installing... • Installing pymdown-extensions (8.2): Pending... • Installing pymdown-extensions (8.2): Installing... • Installing mkdocs-material-extensions (1.0.1): Installing... • Installing pymdown-extensions (8.2): Installing... • Installing mkdocs-autorefs (0.2.1): Installing... • Installing mkdocs-material-extensions (1.0.1): Installing... • Installing pymdown-extensions (8.2): Installing... • Installing pymdown-extensions (8.2): Installing... • Installing mkdocs-material-extensions (1.0.1) • Installing pymdown-extensions (8.2): Installing... • Installing mkdocs-material-extensions (1.0.1) • Installing pymdown-extensions (8.2): Installing... • Installing mkdocs-autorefs (0.2.1) • Installing mkdocs-material-extensions (1.0.1) • Installing pymdown-extensions (8.2): Installing... • Installing pymdown-extensions (8.2) • Installing mkdocs-material (7.1.8): Pending... • Installing mkdocstrings (0.15.2): Pending... • Installing mkdocstrings (0.15.2): Downloading... 0% • Installing mkdocstrings (0.15.2): Downloading... 100% • Installing mkdocstrings (0.15.2): Downloading... 100% • Installing mkdocstrings (0.15.2): Installing... • Installing mkdocstrings (0.15.2): Installing... • Installing mkdocs-material (7.1.8): Downloading... 0% • Installing mkdocstrings (0.15.2): Installing... • Installing mkdocstrings (0.15.2): Installing... • Installing mkdocs-material (7.1.8): Downloading... 30% • Installing mkdocstrings (0.15.2): Installing... • Installing mkdocstrings (0.15.2): Installing... • Installing mkdocs-material (7.1.8): Downloading... 80% • Installing mkdocstrings (0.15.2): Installing... • Installing mkdocstrings (0.15.2): Installing... • Installing mkdocs-material (7.1.8): Downloading... 100% • Installing mkdocstrings (0.15.2): Installing... • Installing mkdocstrings (0.15.2): Installing... • Installing mkdocs-material (7.1.8): Downloading... 100% • Installing mkdocstrings (0.15.2): Installing... • Installing mkdocstrings (0.15.2): Installing... • Installing mkdocs-material (7.1.8): Installing... • Installing mkdocstrings (0.15.2): Installing... • Installing mkdocstrings (0.15.2) • Installing mkdocstrings (0.15.2) • Installing mkdocs-material (7.1.8) • Installing mkdocstrings (0.15.2) The following packages are already present in the pyproject.toml and will be skipped: • pytkdocs If you want to update it to the latest compatible version, you can use `poetry update package`. If you prefer to upgrade it to the latest available version, you can use `poetry add package@latest`. Nothing to add.
Now that we have mkdocs installed, we could initialize some docs
In [21]:
! poetry run mkdocs new .
INFO - Writing config file: ./mkdocs.yml INFO - Writing initial docs: ./docs/index.md
In [23]:
! ls
README.rst mkdocs.yml pyproject.toml tests docs poetry.lock src
Now we have a mkdocs.yml file, and a docs directory.
In [24]:
! ls docs
index.md
Easy! Let's write a function.
In [29]:
%%writefile src/demo/demo.py
import numpy as np
def sin(x):
"""Function to create sin(x)
Parameters
----------
x : np.ndarray, float
Input x values
Returns
-------
result : np.ndarray
Sine of x.
"""
return np.sin(x)
Writing src/demo/demo.py
Now let's write a test!
In [39]:
%%writefile tests/test_sin.py
import numpy as np
from demo.demo import sin
def test_sin():
"""Test that `sin` produces the correct result"""
assert sin(0) == 0
assert sin(np.pi/2) == 1
Writing tests/test_sin.py
Now we can run pytest, and check out tests pass! (Note, you might have to add pytest as a development dependency!)
In [41]:
! poetry run pytest src/ tests/
============================= test session starts ============================== platform darwin -- Python 3.8.7, pytest-5.4.3, py-1.10.0, pluggy-0.13.1 rootdir: /Users/ch/repos/astronomy_workflow/docs/notebooks/3.0-building/demo/demo plugins: anyio-3.1.0 collected 0 items / 2 errors ==================================== ERRORS ==================================== _____________________ ERROR collecting tests/test_demo.py ______________________ ImportError while importing test module '/Users/ch/repos/astronomy_workflow/docs/notebooks/3.0-building/demo/demo/tests/test_demo.py'. Hint: make sure your test modules/packages have valid Python names. Traceback: tests/test_demo.py:1: in <module> from demo import __version__ E ModuleNotFoundError: No module named 'demo' ______________________ ERROR collecting tests/test_sin.py ______________________ ImportError while importing test module '/Users/ch/repos/astronomy_workflow/docs/notebooks/3.0-building/demo/demo/tests/test_sin.py'. Hint: make sure your test modules/packages have valid Python names. Traceback: tests/test_sin.py:2: in <module> from demo.demo import sin E ModuleNotFoundError: No module named 'demo' =========================== short test summary info ============================ ERROR tests/test_demo.py ERROR tests/test_sin.py !!!!!!!!!!!!!!!!!!! Interrupted: 2 errors during collection !!!!!!!!!!!!!!!!!!!! ============================== 2 errors in 5.09s ===============================
Uh oh, no module named demo?
We never actually installed our own package! Let's do that now
In [42]:
! poetry install
Installing dependencies from lock file No dependencies to install or update Installing the current project: demo (0.1.01mInstalling the current project: demo (0.1.0)
Now we've installed our package, our tests should pass.
In [43]:
! poetry run pytest src/ tests/
============================= test session starts ============================== platform darwin -- Python 3.8.7, pytest-5.4.3, py-1.10.0, pluggy-0.13.1 rootdir: /Users/ch/repos/astronomy_workflow/docs/notebooks/3.0-building/demo/demo plugins: anyio-3.1.0 collected 2 items tests/test_demo.py . [ 50%] tests/test_sin.py . [100%] ============================== 2 passed in 0.08s ===============================
They do! (Note there is a default test that was initialized by poetry, which checks the version number is 0.1.0!)
Now we have a package with a module, and a passing test, let's create our documentation.
In [44]:
%%writefile docs/demo.md
# Documentation for `demo`
::: demo.demo
handler: python
selection:
members:
- sin
rendering:
show_root_heading: false
show_source: false
Writing docs/demo.md
We're going to need to alter the mkdocs.yaml file, right now it looks like this
In [48]:
! head mkdocs.yml
site_name: My Docs site_url: https://example.com/
Let's write the following out to mkdocs.yaml, which will set up our default index.md as the landing page, our new demo.md file, will use the material theme, and will automatically document our docstrings!
In [54]:
%%writefile mkdocs.yml
site_name: PSFMachine
nav:
- Home: index.md
- Demo: demo.md
theme:
name: "material"
plugins:
- search
- mkdocstrings:
default_handler: python
handlers:
python:
selection:
docstring_style: "numpy"
rendering:
show_source: false
custom_templates: templates
watch:
- src/demo
Overwriting mkdocs.yml
We can now test our docs using mkdocs serve, which will serve the documentation to a local host.
In [56]:
! poetry run mkdocs serve
INFO - Building documentation... WARNING - Config value: 'site_url'. Warning: This option is now required. Set to a valid URL or an empty string to avoid an error in a future release. WARNING - Config value: 'site_url'. Warning: The 'use_directory_urls' option has been disabled because 'site_url' contains an empty value. Either define a valid URL for 'site_url' or set 'use_directory_urls' to False. INFO - Cleaning site directory INFO - Documentation built in 0.40 seconds INFO - [18:45:17] Serving on http://127.0.0.1:8000/ INFO - [18:45:20] Browser connected: http://127.0.0.1:8000/demo.html ^C INFO - Shutting down...
If you use the cell above you should see something like this, which is the documentation for our function.
This looks great! If we now wanted to store this on GitHub, we might want a .gitignore file to makes sure we don't track everything
In [59]:
ls -a
./ .venv/ mkdocs.yaml pyproject.toml ../ README.rst mkdocs.yml src/ .pytest_cache/ docs/ poetry.lock tests/
In [60]:
%%writefile .gitignore
__pycache__
.ipynb_checkpoints
.pytest_cache
site/
.venv
Writing .gitignore
If we want to track these files with git we can use
git initTo start a new repository
In [61]:
! git init
Initialized empty Git repository in /Users/ch/repos/astronomy_workflow/docs/notebooks/3.0-building/demo/demo/.git/
We can check the status
In [63]:
! git status
On branch master No commits yet Untracked files: (use "git add <file>..." to include in what will be committed) .gitignore README.rst docs/ mkdocs.yml poetry.lock pyproject.toml src/ tests/ nothing added to commit but untracked files present (use "git add" to track)
We probably want to track all these files, so we can add them all using
In [64]:
! git add .
Now we can use git commit to commit these changes, and version control what we've done so far.
In [65]:
! git commit -m 'first commit'
[master (root-commit) d90c949] first commit 12 files changed, 1757 insertions(+) create mode 100644 .gitignore create mode 100644 README.rst create mode 100644 docs/demo.md create mode 100644 docs/index.md create mode 100644 mkdocs.yml create mode 100644 poetry.lock create mode 100644 pyproject.toml create mode 100644 src/demo/__init__.py create mode 100644 src/demo/demo.py create mode 100644 tests/__init__.py create mode 100644 tests/test_demo.py create mode 100644 tests/test_sin.py
If we wanted to, we could now add a remote, and push these changes to GitHub!
If we want to push our docs page to our remote GitHub, we would use
poetry run mkdocs gh-deploy(You might need to tweak mkdocs.yml).
Finally, if we wanted to publish our package to PyPI, we would use
poetry publishIf we want to add GitHub actions, we would need to make a workflows directory and add some more .yml files. If we want to use black or flake8 we can install them as development dependencies and run them
In [66]:
! poetry add -D black
Using version ^21.6b0 for black Updating dependencies Resolving dependencies... (0.9s) Writing lock file Package operations: 6 installs, 0 updates, 0 removals • Installing appdirs (1.4.4): Pending... • Installing mypy-extensions (0.4.3): Pending... • Installing pathspec (0.8.1): Pending... • Installing regex (2021.4.4): Pending... • Installing toml (0.10.2): Pending... • Installing mypy-extensions (0.4.3): Pending... • Installing pathspec (0.8.1): Pending... • Installing regex (2021.4.4): Pending... • Installing toml (0.10.2): Pending... • Installing appdirs (1.4.4): Installing... • Installing mypy-extensions (0.4.3): Pending... • Installing pathspec (0.8.1): Pending... • Installing regex (2021.4.4): Pending... • Installing toml (0.10.2): Pending... • Installing toml (0.10.2): Installing... • Installing toml (0.10.2): Installing... • Installing regex (2021.4.4): Installing... • Installing toml (0.10.2): Installing... • Installing pathspec (0.8.1): Pending... • Installing regex (2021.4.4): Installing... • Installing toml (0.10.2): Installing... • Installing mypy-extensions (0.4.3): Installing... • Installing pathspec (0.8.1): Pending... • Installing regex (2021.4.4): Installing... • Installing toml (0.10.2): Installing... • Installing regex (2021.4.4): Installing... • Installing toml (0.10.2): Installing... • Installing pathspec (0.8.1): Installing... • Installing regex (2021.4.4): Installing... • Installing toml (0.10.2): Installing... • Installing toml (0.10.2) • Installing mypy-extensions (0.4.3): Installing... • Installing pathspec (0.8.1): Installing... • Installing regex (2021.4.4): Installing... • Installing toml (0.10.2) • Installing appdirs (1.4.4) • Installing mypy-extensions (0.4.3): Installing... • Installing pathspec (0.8.1): Installing... • Installing regex (2021.4.4): Installing... • Installing toml (0.10.2) • Installing pathspec (0.8.1): Installing... • Installing regex (2021.4.4): Installing... • Installing toml (0.10.2) • Installing mypy-extensions (0.4.3) • Installing pathspec (0.8.1): Installing... • Installing regex (2021.4.4): Installing... • Installing toml (0.10.2) • Installing toml (0.10.2) • Installing regex (2021.4.4) • Installing toml (0.10.2) • Installing regex (2021.4.4) • Installing toml (0.10.2) • Installing pathspec (0.8.1) • Installing regex (2021.4.4) • Installing toml (0.10.2) • Installing black (21.6b0): Pending... • Installing black (21.6b0): Downloading... 0% • Installing black (21.6b0): Downloading... 100% • Installing black (21.6b0): Downloading... 100% • Installing black (21.6b0): Installing... • Installing black (21.6b0)
In [67]:
! poetry run black src
reformatted src/demo/__init__.py reformatted src/demo/demo.py All done! ✨ 🍰 ✨ 2 files reformatted.