forked from datajoint/datajoint-python
-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
1 parent
083bee2
commit fec90c4
Showing
5 changed files
with
137 additions
and
163 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,115 @@ | ||
| # Develop | ||
|
|
||
| Included with the codebase is the recommended development environment configured using [DevContainer](https://containers.dev/). | ||
|
|
||
| ## Launch Development Environment | ||
|
|
||
| Here are some options that provide a great developer experience: | ||
|
|
||
| - **Cloud-based IDE**: (*recommended*) Launch using the [GitHub Codespaces](https://github.com/features/codespaces) named `Development`. | ||
| - **Local IDE**: | ||
| - Ensure you have [Git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git) | ||
| - Ensure you have [Docker](https://docs.docker.com/get-docker/) | ||
| - Ensure you have [VSCode](https://code.visualstudio.com/) | ||
| - Install the [Dev Containers extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) | ||
| - `git clone` the codebase repository and open it in VSCode | ||
| - Use the `Dev Containers extension` to `Reopen in Container` (More info in the `Getting started` included with the extension) | ||
| - Your environment will finish loading once the file tree is populated and the terminal become active | ||
|
|
||
| ## Features | ||
|
|
||
| Once you've successfully launched the development environment, you'll be able to take advantage of our developer tooling to help improve productivity. | ||
|
|
||
| ### Syntax Tests | ||
|
|
||
| The following will verify that there are no syntax errors. | ||
|
|
||
| ``` | ||
| flake8 datajoint --count --select=E9,F63,F7,F82 --show-source --statistics | ||
| ``` | ||
|
|
||
| ### Integration Tests | ||
|
|
||
| The following will verify there are no regression errors by running our test suite of unit and integration tests. | ||
|
|
||
| - Entire test suite: | ||
| ``` | ||
| nosetests -vw tests | ||
| ``` | ||
| - A single functional test: | ||
| ``` | ||
| nosetests -vs --tests=tests.test_external_class:test_insert_and_fetch | ||
| ``` | ||
| - A single class test: | ||
| ``` | ||
| nosetests -vs --tests=tests.test_fetch:TestFetch.test_getattribute_for_fetch1 | ||
| ``` | ||
|
|
||
| ### Style Tests | ||
|
|
||
| The following will verify that there are no code styling errors. | ||
|
|
||
| ``` | ||
| flake8 --ignore=E203,E722,W503 datajoint --count --max-complexity=62 --max-line-length=127 --statistics | ||
| ``` | ||
|
|
||
| The following will ensure the codebase has been formatted with [black](https://black.readthedocs.io/en/stable/). | ||
|
|
||
| ``` | ||
| black datajoint --check -v | ||
| ``` | ||
|
|
||
| The following will ensure the test suite has been formatted with [black](https://black.readthedocs.io/en/stable/). | ||
|
|
||
| ``` | ||
| black tests --check -v | ||
| ``` | ||
|
|
||
| ### Jupyter | ||
|
|
||
| Jupyter notebooks are supported in this environment. This means that when you `import datajoint`, it will use the current state of the source. | ||
|
|
||
| Be sure to see the reference documenation if you are new to [running Jupyter notebooks w/ VSCode](https://code.visualstudio.com/docs/datascience/jupyter-notebooks#_create-or-open-a-jupyter-notebook). | ||
|
|
||
| ### Debugger | ||
|
|
||
| [VSCode Debugger](https://code.visualstudio.com/docs/editor/debugging) is a powerful tool that can really accelerate fixes. | ||
|
|
||
| Try it as follows: | ||
|
|
||
| - Create a python script of your choice | ||
| - `import datajoint` (This will use the current state of the source) | ||
| - Add breakpoints by adding red dots next to line numbers | ||
| - Select the `Run and Debug` tab | ||
| - Start by clicking the button `Run and Debug` | ||
|
|
||
| ### MySQL CLI | ||
|
|
||
| It is often useful in development to connect to DataJoint's relational database backend directly using the MySQL CLI. | ||
|
|
||
| Connect as follows to the database running within your developer environment: | ||
|
|
||
| ``` | ||
| mysql -hfakeservices.datajoint.io -uroot -psimple | ||
| ``` | ||
|
|
||
| ### Documentation | ||
|
|
||
| Our documentation is built using [MkDocs Material](https://squidfunk.github.io/mkdocs-material/). The easiest way to improve the documentation is by using the `docs/docker-compose.yaml` environment. The source can be modified in `docs/src` using markdown. | ||
|
|
||
| The docs environment can be run using 3 modes: | ||
|
|
||
| - **LIVE**: (*recommended*) This serves the docs locally. It supports live reloading on saves to `docs/src` files but does not support the docs version dropdown. Useful to see changes live. | ||
| ``` | ||
| MODE="LIVE" PACKAGE=datajoint UPSTREAM_REPO=https://github.com/datajoint/datajoint-python.git HOST_UID=$(id -u) docker compose -f docs/docker-compose.yaml up --build | ||
| ``` | ||
| - **QA**: This serves the docs locally. It supports the docs version dropdown but does not support live reloading. Useful as a final check. | ||
| ``` | ||
| MODE="QA" PACKAGE=datajoint UPSTREAM_REPO=https://github.com/datajoint/datajoint-python.git HOST_UID=$(id -u) docker compose -f docs/docker-compose.yaml up --build | ||
| ``` | ||
| - **BUILD**: This compiles the docs. Most useful for the docs deployment automation. Other modes are more useful to new contributors. | ||
| ``` | ||
| MODE="BUILD" PACKAGE=datajoint UPSTREAM_REPO=https://github.com/datajoint/datajoint-python.git HOST_UID=$(id -u) docker compose -f docs/docker-compose.yaml up --build | ||
| ``` | ||
|
|
||
| When the docs are served locally, use the VSCode `PORTS` tab (next to `TERMINAL`) to manage access to the forwarded ports. Docs are served on port `8080`. |