From 1e6eee08db86f16373e057cfc236487993485352 Mon Sep 17 00:00:00 2001 From: troyraen Date: Sun, 11 Feb 2024 15:24:04 -0800 Subject: [PATCH] add docs for developers --- .../for-developers/setup-development-mode.md | 40 +++++++++++++++++++ docs/source/index.rst | 7 ++++ 2 files changed, 47 insertions(+) create mode 100644 docs/source/for-developers/setup-development-mode.md diff --git a/docs/source/for-developers/setup-development-mode.md b/docs/source/for-developers/setup-development-mode.md new file mode 100644 index 0000000..049611a --- /dev/null +++ b/docs/source/for-developers/setup-development-mode.md @@ -0,0 +1,40 @@ +# Setup Development Mode + +Instructions for setting up development or "editable" mode are given below. This is a way of pip-installing the package from the source code in your local directory which gives you immediate access to your changes, though you may need to re-import the package or re-load the python environment. + +When you are ready to publicly release a new version of `pittgoogle-client`, publish to PyPI using the release process described in [issues #7](https://github.com/mwvgroup/pittgoogle-client/pull/7). + +See also: [Python Packaging User Guide](https://packaging.python.org/en/latest/). + +## Setup + +```bash +# clone the repo and cd in +git clone https://github.com/mwvgroup/pittgoogle-client.git +cd pittgoogle-client + +# recommended to create a new conda env +# use the latest python version unless you have a specific reason not to +conda create --name pittgoogle python=3.12 +conda activate pittgoogle + +# install pittgoogle-client in editable mode. use pwd so that the absolute path is registered. +pip install -e $(pwd) +``` + +## Work in development ("editable") mode: + +Now you can work with the code in your local pittgoogle-client repo in python: + +```python +import pittgoogle + +# make new changes in your local pittgoogle-client repo code +# then use importlib to reload the package with the new changes +import importlib +importlib.reload(pittgoogle) +# if you don't have access to the new changes at this point, try reloading again +# if that doesn't work, restart your python interpreter +``` + +See also: [Working in “development mode”](https://packaging.python.org/guides/distributing-packages-using-setuptools/#working-in-development-mode). diff --git a/docs/source/index.rst b/docs/source/index.rst index e17ab2f..c5e383c 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -23,6 +23,13 @@ tutorials/cloud-storage tutorials/ztf-figures +.. toctree:: + :caption: For Developers + :maxdepth: 3 + :hidden: + + for-developers/setup-development-mode + .. toctree:: :caption: API Reference :maxdepth: 3