Developer Guide#

We welcome and encourage all kind of help, such as bug reports, bug fixes, documentation improvements, enhancements, ideas, marketing and communications, devops, project coordination, etc.

Setup your work environment as follows:

git clone https://github.com/awslabs/amazon-accessible-rl-sdk.git
# Alternative: git clone git@github.com:awslabs/amazon-accessible-rl-sdk.git

cd amazon-accessible-rl-sdk

# Perform editable install (preferrably to a virtual environment) so that
# changes to the code base will be reflected immediately.
pip install -e .

Once the command completes, you’ll have a local repository at ./amazon-accessible-rl-sdk/. Apart from source codes, you should notice these additional requirement files:

`requirements-test.txt`	Required for unit tests
`requirements-docs.txt`	Required to generate the html documentations.
`requirements-build.txt`	Required to build the wheel.
`requirements-dev.txt`	Recommended packages during development.

Hygiene Practice#

Although the project repository implements code checks in its CI process, you’re still strongly recommended to run the checks locally to quickly catch and fix low-hanging-fruit violations.

Required packages and tools can be installed as:

pip install -r <(cat requirements-*.txt)

Linters#

The code-base comes with a set of git pre-commit hooks listed in the .pre-commit-config.yaml file.

pre-commit install

Unit Tests#

Unit tests are done using the pytest framework.

We require that your contributions do not break existing tests. And if you found the existing tests are buggy, please report it or feel free to contribute your fixes.

You should also include new tests whenever it makes sense (and you’d be the one who makes the judgement call).

As a rule of thumb:

new tests for every new capability (e.g., new API, changing API)
new tests for every bug reported as an issue, because this means that the existing tests were not exhaustive enough to catch the bug.

Below are a few typical ways to run pytest. Please consult pytest documentation for more details.

# Run all unit tests
pytest

# Run all unit tests with increased verbosity
pytest -v -rA

# Run a specific test file
pytest test/test_dataframe.py

# Run a specific unit test
pytest test/test_dataframe.py::test_df

# Only run tests which match the given substring test names.
pytest -k test_from

# Similar to above, but only for unit tests in the given test file.
pytest test/test_dataframe.py -k test_from

Code Coverage#

Code coverage are computed using the coverage tool.

coverage run -m pytest

# View the summary
coverage report

# Generage a detailed html report to htmlcov/.
# To view the detailed report, open htmlcov/index.html.
coverage html

Type Checks#

Note

If you’re new to type checks, we encourage you to learn more about its benefits and how-to on mypy and Python official documentation.

As a pre-requisite, you need to enable type hints on your pandas installations:

# See: https://pandas.pydata.org/docs/dev/development/contributing_codebase.html#testing-type-hints-in-code-using-pandas
python -c "import pandas; import pathlib; (pathlib.Path(pandas.__path__[0]) / 'py.typed').touch()"

Then, run the type checks as follows:

mypy --install-types .

HTML Docs#

Portion of the documentations are written as Jupyter notebooks (i.e., notebooks/*.ipynb files). As such, you need to install pandoc on your computer by consulting their installation instructions.

You also need mermaid-cli to build Mermaid diagrams. To install on your computer, please refer to its installation instructions. NOTE: this is a workaround until this issue is fixed.

We recommend that you check the correctness of the inline code in the API docstrings:

pytest src/a2rl

Should you encounter failed cases, we highly encourage you to report this as a new issue.

Then, generate the html documentations as follows:

cd docs
make clean
make html

On a multi-core machine, you can also pass the -j <num> to speed-up the build process.

cd docs
make clean

Once completed, you can view the generated html pages at docs/_build/html/index.html.

Note

Here’re a few tricks to speed-up the build time, especially when writing documentations.

You may speed-up the time to build notebook examples:

cd docs
make clean
NOTEBOOK_FAST_RUN=1 make html

You may also skip the notebook examples altogether:

cd docs
make clean
NO_NOTEBOOKS=1 make html

Tip

VS Code users may consider the Live Preview extension to auto-refresh the preview of the generated HTML pages after every make html.

Wheel File#

Generate the .whl file as follow:

python -m build --wheel --no-isolation

To clean-up the build artifacts:

VIRTUAL_ENV='' python setup.py clean --all

To clean-up the build artifacts and your currently active virtual environment:

python setup.py clean --all