diff --git a/docs/contribute/pre-commit-hooks.md b/docs/contribute/pre-commit-hooks.md new file mode 100644 index 000000000..4e8827f1e --- /dev/null +++ b/docs/contribute/pre-commit-hooks.md @@ -0,0 +1,53 @@ +# Pre-Commit Hooks + +We use [`pre-commit`](https://pre-commit.com) to manage pre-commit hooks. + +Pre-commit hooks are programs which run before each git commit, and can read and potentially modify the files which are to be committed. + +We use pre-commit hooks to: +- enforce coding guidelines, including the `python` style-guide [PEP8](https://peps.python.org/pep-0008/) (`black` and `flake8`), +- to check the order of `import` statements (`isort`), +- to check the types of `python` objects (`mypy`). + +The hooks and their settings are specified in the `.pre-commit-config.yaml` in each repository. + +## Handling Pre-Commit Hook Errors + +If your `git commit` fails because of the pre-commit hook, then you should: + +1. Run the pre-commit hooks on the files which you have staged, by running the following command in your terminal: + ```zsh + $ pre-commit run + ``` + +2. Inspect the output. It might look like this: + ``` + $ pre-commit run + black....................Passed + isort....................Passed + flake8...................Passed + mypy.....................Failed + - hook id: mypy + - exit code: 1 + + example.py:33: error: Need type annotation for "data" (hint: "data: Dict[, ] = ...") + Found 1 errors in 1 files (checked 10 source files) + ``` +3. Fix any errors which are reported. + **Important: Once you've changed the code, re-stage the files it to Git. + This might mean un-staging changes and then adding them again.** +4. If you have trouble: + - Do a web-search to see if someone else had a similar error in the past. + - Check that the tests you've written work correctly. + - Check that there aren't any other obvious errors with the code. + - If you've done all of that, and you still can't fix the problem, get help from someone else on the team. +5. Repeat 1-4 until all hooks return "passed", e.g. + ``` + $ pre-commit run + black....................Passed + isort....................Passed + flake8...................Passed + mypy.....................Passed + ``` + +It's easiest to solve these kinds of problems if you make small commits, often. diff --git a/docs/contribute/setup.md b/docs/contribute/setup.md index 93d93ce5e..d30244df0 100644 --- a/docs/contribute/setup.md +++ b/docs/contribute/setup.md @@ -3,236 +3,163 @@ It's possible to set up your python environment in many different ways. To use the AutoRA package you need: -- `python` and packages as specified in the `pyproject.toml` file, -!!! success - We recommend setting up your development environment using `virtualenv`, which creates isolated python environments. +- `python` and +- packages as specified in the `pyproject.toml` file. To develop the AutoRA package, you also need: + - `git`, the source control tool, - `pre-commit` which is used for handling git pre-commit hooks. You should also consider using an IDE. We recommend: -- PyCharm. This is a `python`-specific integrated development environment which comes with extremely powerful tools + +- PyCharm. This is a `python`-specific integrated development environment which comes with useful tools for changing the structure of `python` code, running tests, etc. -- Visual Studio Code. This is a powerful general text editor with plugins to support `python` development. +- Visual Studio Code. This is a powerful general text editor with plugins to support `python` development. The following sections describe how to install and configure the recommended setup for developing AutoRA. -- You should be familiar with the command line for your operating system. The topics required are covered in: -- **macOS**: Joe Kissell. [*Take Control of the Mac Command Line with Terminal, 3rd Edition*](https://bruknow.library.brown.edu/permalink/01BU_INST/528fgv/cdi_safari_books_v2_9781947282513). Take Control Books, 2022. Chapters *Read Me First* through *Bring the Command Line Into The Real World*. -- **Linux**: William E. Shotts. [*The Linux Command Line: a Complete Introduction. 2nd edition.*](https://bruknow.library.brown.edu/permalink/01BU_INST/9mvq88/alma991043239704906966). No Starch Press, 2019. Parts *I: Learning the Shell* and *II: Configuration and the Environment*. - -## Development Setup on macOS - -### Prerequisites +!!! tip + It is helpful to be familiar with the command line for your operating system. The topics required are covered in: -For macOS, we strongly recommend using `homebrew` to manage packages. + - **macOS**: Joe Kissell. [*Take Control of the Mac Command Line with Terminal, 3rd Edition*](https://bruknow.library.brown.edu/permalink/01BU_INST/528fgv/cdi_safari_books_v2_9781947282513). Take Control Books, 2022. Chapters *Read Me First* through *Bring the Command Line Into The Real World*. + - **Linux**: William E. Shotts. [*The Linux Command Line: a Complete Introduction. 2nd edition.*](https://bruknow.library.brown.edu/permalink/01BU_INST/9mvq88/alma991043239704906966). No Starch Press, 2019. Parts *I: Learning the Shell* and *II: Configuration and the Environment*. -Visit [https://brew.sh](https://brew.sh) and run the installation instructions. - -### Clone Repository - -We recommend using the GitHub Desktop Application to clone the repository. Install it: - -```shell -brew install --cask github -``` +## Development Setup -Clone the repository by: -- opening the GitHub Desktop application, then -- opening File > Clone Repository and -- selecting the repository you would like to clone. +### Clone the Repository -It may prompt you to authenticate, and should clone the repository to a new directory. This directory is referred -to as the `` in the rest of this readme. +The easiest way to clone the repo is to go to [the repository page on GitHub](https://github.com/AutoResearch/autora) +and click the "<> Code" button and follow the prompts. +!!! hint + We recommend using: + + - the [GitHub Desktop Application](https://desktop.github.com) on macOS or Windows, or + - the [GitHub command line utility](https://cli.github.com) on Linux. ### Install `python` -We recommend using `pyenv` to manage `python` versions. - -#### Initialize `pyenv` - -Install `pyenv` by running: -```shell -brew install pyenv -``` - -Run its initialization script as follows: - -```shell -pyenv init -``` -... and follow the instructions to add `pyenv` to the `$PATH` by editing the interactive shell configuration -file, `.zshrc` or `.bashrc`. - -!!! hint - If it exists, this file is a hidden file ([dotfile](https://missing.csail.mit.edu/2019/dotfiles/)) in your home - directory. You can create or edit this file using a text editor or with CLI commands. Add the lines of script from - the `pyenv init` response to the `.zshrc` file if they are not already present. +!!! success + All contributions to the AutoRA core packages should work under **python 3.8**, so we recommend using that version + for development. + -#### Restart shell session +You can install python: -After making these changes, restart your shell session by executing: +- Using the instructions at [python.org](https://www.python.org), or +- Using a package manager, e.g. + [homebrew](https://docs.brew.sh/Homebrew-and-Python), + [pyenv](https://github.com/pyenv/pyenv), + [asdf](https://github.com/asdf-community/asdf-python), + [rtx](https://github.com/jdxcode/rtx/blob/main/docs/python.md), + [winget](https://winstall.app/apps/Python.Python.3.8). +If successful, you should be able to run python in your terminal emulator like this: ```shell -exec "$SHELL" +python ``` -#### Install `python` - -Install `python` (version 3.8 or newer). - -You could install version 3.8 as follows: - -```shell -pyenv install 3.8 +...and see some output like this: ``` - -### Install Pre-Commit Hooks - -If you wish to commit to the repository, you should install `pre-commit`: -```shell -brew install pre-commit +Python 3.11.3 (main, Apr 7 2023, 20:13:31) [Clang 14.0.0 (clang-1400.0.29.202)] on darwin +Type "help", "copyright", "credits" or "license" for more information. ``` -Activate the pre-commit hooks as follows: -```shell -pre-commit install -``` +#### Create a virtual environment -For more information on pre-commit hooks, see [Pre-Commit-Hooks](#pre-commit-hooks) - -### Configure your development environment - -There are two suggested options for initializing an environment: -- _(Recommended)_ Using PyCharm, -- _(Advanced)_ Using `pip` from the command line. - -#### PyCharm configuration - -Set up the Virtual environment – an isolated version of `python` and all the packages required to run AutoRA and develop it further – as follows: -- Open the `` in PyCharm. -- Navigate to PyCharm > Preferences > Project: AutoRA > Python Interpreter -- Next to the drop-down list of available interpreters, click the "Add Interpreter" and choose "Add Local Interpreter" to initialize a new interpreter. -- Select "virtualenv environment" in the list on the left. Specify the following: - - Environment: new - - Location: `/venv` - - Python executable: the path to the installed `python` version you wish to use, e.g. - `~/.pyenv/versions/3.8.16/bin/python3` - - Click "OK" and wait while the environment builds. - -- Open a terminal in PyCharm. - - Check that the virtualenvironment is active – run - ```shell - which python - ``` - which should return the path to the python in - your virtualenv, e.g. `/venv/bin/python`. If it is not, activate the environment by running - ```shell - source venv/bin/activate - ``` - - Use `pip install` to install the current project (`"."`) in editable mode (`--editable`) - with dev-dependencies (`[dev]`), - ensuring that everything is updated (`--upgrade`): - ```shell - pip install --upgrade --editable ".[dev]" - ``` - - Run the tests using: - ```shell - pytest --doctest-modules - ``` - -#### Command Line Setup +!!! success + We recommend setting up your development environment using a manager like `venv`, which creates isolated python + environments. Other environment managers, like + [virtualenv](https://virtualenv.pypa.io/en/latest/), + [pipenv](https://pipenv.pypa.io/en/latest/), + [virtualenvwrapper](https://virtualenvwrapper.readthedocs.io/en/latest/), + [hatch](https://hatch.pypa.io/latest/), + [poetry](https://python-poetry.org), + are available and will likely work, but will have different syntax to the syntax shown here. -If you need more control over the `virtualenv` environment, then you can set up a new environment from the command line. + Our packages are set up using `virtualenv` with `pip` -From the ``, run the following commands. +In the ``, run the following command to create a new virtual environment in the `.venv` directory -Set up a new virtualenv environment with an installed version of `python` version in the `venv` directory: ```shell -virtualenv --python="/path/to/your/python/installation" venv +python3 -m "venv" ".venv" ``` -Activate the environment +Activate it by running ```shell -source venv/bin/activate +source ".venv/bin/activate" ``` -Update the installation utilities within the new environment: +#### Install dependencies + +Upgrade pip: ```shell -pip install --upgrade pip setuptools wheel +pip install --upgrade pip ``` -Install and upgrade all the dependencies: +Install the current project development dependencies: ```shell pip install --upgrade --editable ".[dev]" ``` -Once this step has been completed, skip to the section [Activating and using the environment](#activating-and-using-the-environment) to test it. +Your IDE may have special support for python environments. For IDE-specific setup, see: -#### Visual Studio Code Configuration +- [PyCharm Documentation](https://www.jetbrains.com/help/pycharm/configuring-python-interpreter.html) +- [VSCode Documentation](https://code.visualstudio.com/docs/python/environments) -After installing Visual Studio Code and the other prerequisites, carry out the following steps: - -- Open the `` in Visual Studio Code -- Install the Visual Studio Code plugin recommendations suggested with the project. These include: - - `python` - - `python-environment-manager` -- Run the [Command Line Setup](#command-line-setup) specified above. This can be done in the built-in terminal if desired (Menu: Terminal > New Terminal). -- Select the `python` option in the vertical bar on the far left of the window (which appear after installing the plugins). Under the title "PYTHON: ENVIRONMENTS" should be a list of `python` environments. If these do not appear: - - Refresh the window pane - - Ensure the python-environment-manager is installed correctly. - - Ensure the python-environment-manager is activated. - -- Locate the correct `virtualenv` environment. Click the "thumbs up" symbol next to the environment name to - "set as active workspace interpreter". - -- Check that the `virtualenv` environment is correctly set-up. - - Open a new terminal within Visual Studio Code (Menu: Terminal > New Terminal). - - It should execute something like `source /venv/bin/activate` before offering you a prompt. - - If you execute `which python` it should return the path to your python executable in the `.../venv/bin` directory. - - Ensure that there are no errors when you run: - ```shell - pytest --doctest-modules - ``` - in the built-in terminal. ### Activating and using the environment -#### Using `virtualenv` interactively - To run interactive commands, you can activate the virtualenv environment. From the `` directory, run: ```shell -source venv/bin/activate +source ".venv/bin/activate" ``` This spawns a new shell where you have access to the `python` and all the packages installed using `pip install`. You should see the prompt change: ``` -% source venv/bin/activate -(venv) % +% source .venv/bin/activate +(.venv) % ``` + If you execute `python` and then `import numpy`, you should be able to see that `numpy` has been imported from the -`venv` environment: +`.venv` environment: ``` -(venv) % python +(.venv) % python Python 3.8.16 (default, Dec 15 2022, 14:31:45) [Clang 14.0.0 (clang-1400.0.29.202)] on darwin Type "help", "copyright", "credits" or "license" for more information. >>> import numpy >>> numpy - + >>> exit() -(venv) % +(.venv) % +``` + +You should be able to check that the current project works by running the tests: +```shell +pytest ``` +It should return something like: + +``` +% pytest +. +-------------------------------- +Ran 1 test in 0.000s + +OK +``` + + !!! hint To deactivate the `virtualenv` environment, `deactivate` it. This should return you to your original prompt, as follows: @@ -242,19 +169,19 @@ Type "help", "copyright", "credits" or "license" for more information. ``` -#### Running code non-interactively +### Running code non-interactively You can run python programs without activating the environment, by using `/path/to/python run {command}`. For example, to run unittests tests, execute: ```shell -venv/bin/python -m pytest +.venv/bin/python -m pytest ``` It should return something like: ``` -% venv/bin/python -m pytest +% .venv/bin/python -m pytest . -------------------------------- Ran 1 test in 0.000s @@ -262,67 +189,18 @@ Ran 1 test in 0.000s OK ``` -## Development Setup on Windows - -Windows is not yet officially supported. You may be able to follow the same approach as for macOS to set up your -development environment, with some modifications, e.g. using `winget` in place of `homebrew`, - -If you successfully set up AutoRA on Windows, please update this readme. - -## Development Practices - -### Pre-Commit Hooks - -We use [`pre-commit`](https://pre-commit.com) to manage pre-commit hooks. - -Pre-commit hooks are programs which run before each git commit, and can read and potentially modify the files which are to be committed. - -We use pre-commit hooks to: -- enforce coding guidelines, including the `python` style-guide [PEP8](https://peps.python.org/pep-0008/) (`black` and `flake8`), -- to check the order of `import` statements (`isort`), -- to check the types of `python` objects (`mypy`). +### Pre-commit hooks -The hooks and their settings are specified in the `.pre-commit-config.yaml` in each repository. - -See the section [Install Pre-commit Hooks](#install-pre-commit-hooks) for installation instructions. - -#### Handling Pre-Commit Hook Errors +If you wish to commit to the repository, you should install and activate `pre-commit` as follows. +```shell +pip install pre-commit +pre-commit install +``` -If your `git commit` fails because of the pre-commit hook, then you should: +You can run the pre-commit hooks manually by calling: +```shell +pre-commit run --all-files +``` -1. Run the pre-commit hooks on the files which you have staged, by running the following command in your terminal: - ```zsh - $ pre-commit run - ``` +For more information on pre-commit hooks, see [Pre-Commit-Hooks](./pre-commit-hooks.md) -2. Inspect the output. It might look like this: - ``` - $ pre-commit run - black....................Passed - isort....................Passed - flake8...................Passed - mypy.....................Failed - - hook id: mypy - - exit code: 1 - - example.py:33: error: Need type annotation for "data" (hint: "data: Dict[, ] = ...") - Found 1 errors in 1 files (checked 10 source files) - ``` -3. Fix any errors which are reported. - **Important: Once you've changed the code, re-stage the files it to Git. - This might mean un-staging changes and then adding them again.** -4. If you have trouble: - - Do a web-search to see if someone else had a similar error in the past. - - Check that the tests you've written work correctly. - - Check that there aren't any other obvious errors with the code. - - If you've done all of that, and you still can't fix the problem, get help from someone else on the team. -5. Repeat 1-4 until all hooks return "passed", e.g. - ``` - $ pre-commit run - black....................Passed - isort....................Passed - flake8...................Passed - mypy.....................Passed - ``` - -It's easiest to solve these kinds of problems if you make small commits, often. diff --git a/mkdocs.yml b/mkdocs.yml index 28cae65c0..0bb8f1cdc 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -45,6 +45,7 @@ plugins: include_source: true execute: false ignore_h1_titles: true + search: {} markdown_extensions: admonition: {} @@ -53,6 +54,8 @@ markdown_extensions: pymdownx.arithmatex: # required for equation display generic: true pymdownx.snippets: {} + pymdownx.tabbed: + alternate_style: true extra_javascript: [ # requirements for pymdownx.arithmetex: @@ -68,42 +71,44 @@ nav: # - Automated Theorist # TODO: add tutorial from somewhere # - Automated Experimentalist # TODO: add tutorial from somewhere # - Closed-Loop Discovery # TODO: add tutorial from somewhere -- User Guide: - - Theorists: - - Home: 'theorist/index.md' - - DARTS: '!import https://github.com/autoresearch/autora-theorist-darts/?branch=main&extra_imports=["mkdocs/base.yml"]' - - BMS: '!import https://github.com/autoresearch/autora-theorist-bms/?branch=main&extra_imports=["mkdocs/base.yml"]' - - BSR: '!import https://github.com/autoresearch/autora-theorist-bsr/?branch=main&extra_imports=["mkdocs/base.yml"]' - - Experimentalists: - - Home: 'experimentalist/index.md' - - Pipeline: 'core/docs/pipeline/Experimentalist Pipeline Examples.ipynb' - - Samplers: - - Novelty: '!import https://github.com/autoresearch/autora-experimentalist-sampler-novelty/?branch=main&extra_imports=["mkdocs/base.yml"]' - - Inequality: '!import https://github.com/autoresearch/autora-experimentalist-sampler-inequality/?branch=main&extra_imports=["mkdocs/base.yml"]' - - Nearest Value: '!import https://github.com/autoresearch/autora-experimentalist-sampler-nearest-value/?branch=main&extra_imports=["mkdocs/base.yml"]' - - Model Disagreement: '!import https://github.com/autoresearch/autora-experimentalist-sampler-model-disagreement/?branch=main&extra_imports=["mkdocs/base.yml"]' - - Uncertainty: '!import https://github.com/autoresearch/autora-experimentalist-sampler-uncertainty/?branch=main&extra_imports=["mkdocs/base.yml"]' - - Falsification: - - Home: 'falsification/docs/sampler/index.md' - - Quickstart: 'falsification/docs/sampler/quickstart.md' - - Examples: - - Basic Usage: 'falsification/docs/sampler/Basic Usage.ipynb' - - Poolers: - - Falsification: - - Home: 'falsification/docs/pooler/index.md' - - Quickstart: 'falsification/docs/pooler/quickstart.md' - - Examples: - - Basic Usage: 'falsification/docs/pooler/Basic Usage.ipynb' - - Experiment Runners: - - Home: 'experiment-runner/index.md' - - Synthetic: '!import https://github.com/autoresearch/autora-synthetic/?branch=main&extra_imports=["mkdocs/base.yml"]' - - Firebase-Prolific: '!import https://github.com/autoresearch/autora-experiment-runner-firebase-prolific/?branch=main&extra_imports=["mkdocs/base.yml"]' - - Experimentation Managers: - - Firebase: '!import https://github.com/autoresearch/autora-experiment-runner-experimentation-manager-firebase/?branch=main&extra_imports=["mkdocs/base.yml"]' - - Recruitment Managers: - - Prolific: '!import https://github.com/autoresearch/autora-experiment-runner-recruitment-manager-prolific/?branch=main&extra_imports=["mkdocs/base.yml"]' - - Workflow: '!import https://github.com/autoresearch/autora-workflow/?branch=main&extra_imports=["mkdocs/base.yml"]' +#- User Guide: +# - Theorists: +# - Home: 'theorist/index.md' +# - DARTS: '!import https://github.com/autoresearch/autora-theorist-darts/?branch=main&extra_imports=["mkdocs/base.yml"]' +# - BMS: '!import https://github.com/autoresearch/autora-theorist-bms/?branch=main&extra_imports=["mkdocs/base.yml"]' +# - BSR: '!import https://github.com/autoresearch/autora-theorist-bsr/?branch=main&extra_imports=["mkdocs/base.yml"]' +# - Experimentalists: +# - Home: 'experimentalist/index.md' +# - Pipeline: 'core/docs/pipeline/Experimentalist Pipeline Examples.ipynb' +# - Samplers: +# - Novelty: '!import https://github.com/autoresearch/autora-experimentalist-sampler-novelty/?branch=main&extra_imports=["mkdocs/base.yml"]' +# - Inequality: '!import https://github.com/autoresearch/autora-experimentalist-sampler-inequality/?branch=main&extra_imports=["mkdocs/base.yml"]' +# - Nearest Value: '!import https://github.com/autoresearch/autora-experimentalist-sampler-nearest-value/?branch=main&extra_imports=["mkdocs/base.yml"]' +# - Model Disagreement: '!import https://github.com/autoresearch/autora-experimentalist-sampler-model-disagreement/?branch=main&extra_imports=["mkdocs/base.yml"]' +# - Uncertainty: '!import https://github.com/autoresearch/autora-experimentalist-sampler-uncertainty/?branch=main&extra_imports=["mkdocs/base.yml"]' +# - Falsification: +# - Home: 'falsification/docs/sampler/index.md' +# - Quickstart: 'falsification/docs/sampler/quickstart.md' +# - Examples: +# - Basic Usage: 'falsification/docs/sampler/Basic Usage.ipynb' +# - Poolers: +# - Falsification: +# - Home: 'falsification/docs/pooler/index.md' +# - Quickstart: 'falsification/docs/pooler/quickstart.md' +# - Examples: +# - Basic Usage: 'falsification/docs/pooler/Basic Usage.ipynb' +# - Experiment Runners: +# - Home: 'experiment-runner/index.md' +# - Synthetic: '!import https://github.com/autoresearch/autora-synthetic/?branch=main&extra_imports=["mkdocs/base.yml"]' +# - Firebase-Prolific: '!import https://github.com/autoresearch/autora-experiment-runner-firebase-prolific/?branch=main&extra_imports=["mkdocs/base.yml"]' +# - Experimentation Managers: +# - Firebase: '!import https://github.com/autoresearch/autora-experiment-runner-experimentation-manager-firebase/?branch=main&extra_imports=["mkdocs/base.yml"]' +# - Recruitment Managers: +# - Prolific: '!import https://github.com/autoresearch/autora-experiment-runner-recruitment-manager-prolific/?branch=main&extra_imports=["mkdocs/base.yml"]' +# - Workflow: '!import https://github.com/autoresearch/autora-workflow/?branch=main&extra_imports=["mkdocs/base.yml"]' - Contributor Guide: - Overview: 'contribute/index.md' - Module Contributions: 'contribute/module.md' - Core Contributions: 'contribute/core.md' + - Environment Setup: 'contribute/setup.md' + - Pre-Commit Hooks: 'contribute/pre-commit-hooks.md'