Developer Notes#

🚧 This page is under construction.

Please contact us directly if you have questions.

Espresso Architecture#

../_images/espresso_arch.svg
  • Folder contrib/ contains subfolders for each Espresso problem. Each Espresso problem has a self-contained subfolder with problem_name as the folder name.

  • Folder src/cofi_espresso/ contains Espresso core functions and the base class EspressoProblem. Contributors typically install these functions before they start developing a new problem, so that they get access to the base class and utility functions.

    • If you’d like to improve base class specification or cofi_espresso.utils, this is the place to edit.

    • If you’d like to bump the version, change file src/cofi_espresso/_version.py.

  • Folder tools/ has all the utility scripts to be used by contributors and developers.

  • Folder _esp_build/ will contain temporary Python package source files after you build cofi_espresso.

    • These are built files, so you never have to change the contents under this folder. If you feel something’s wrong in this folder, look for the source from the three folders above.

  • Folder docs/ has all the documentation sources.

How-to Guides#

Build the package locally#

Check out the contributor guide.

Build the documentation locally#

Check out README file under docs folder here.

Modify EspressoProblem class#

  1. Modify the class in file src/cofi_espresso/espresso_problem.py

  2. Make sure your changes are backward compatible, otherwise take the responsibility of modifying existing contributions under folder contrib/

  3. Make new contribution generation script compatible with new changes. Check by running file tools/new_contribution/create_new_contrib.py.

    • If generated example doesn’t comply with the new specification, potentially you need to edit some files under tools/new_contribution/_template. Pay special attention to the following files:

      • tools/new_contribution/_template/example_name.py

      • tools/new_contribution/_template/README.md

  4. Ensure build and validation scripts are compatible with new changes. Check by running:

    • tools/build_package/validate.py --pre

    • tools/build_package/build.py

    • tools/build_package/validate.py --post

    • tools/build_package/build_with_checks.py

    Examine reported error (if any) to locate whether to change scripts themselves, or to edit the template files under tools/new_contribution/_template.

  5. Ensure documentations are up to date. The following places need checking:

    • README.md

    • docs/source/user_guide/introduction.rst

    • docs/source/contributor_guide/new_contrib.rst

    • tools/new_contribution/_template/README.md

Modify build/validation scripts#

  1. Navigate to tools/build_package/ folder, all the scripts are there. Make changes as you need.

  2. Ensure the other scripts still work. For example, you might want to change usage of validate.py inside build_with_checks.py after the argument parser is modified. Check by running them on your own.

  3. Ensure documentations are up to date. The following places need checking:

    • tools/README.md

    • tools/new_contribution/_template/README.md

    • docs/source/contributor_guide/new_contrib.rst

Add a new EspressoError#

  1. Add the exception in file src/cofi_espresso/exceptions.py.

  2. Add docstring inside the class itself, and add its name to the docstring of the super class EspressoError.

  3. Add new exception into the list in file docs/source/_templates/exception.rst.

Add a new utility function#

  1. Add the function in folder src/cofi_espresso/utils/.

  2. Write docstring for the function.

  3. Import and add the name to __all__ variable from src/cofi_espresso/utils/__init__.py.

  4. Add the name into docstring at top of src/cofi_espresso/utils/__init__.py.

Change layout of problem-specific documentation#

This refers to the pages for each contribution problem. These pages are dynamically generated by docs/source/_ext/generate_contrib_docs.py. To change the layout of README, metadata and licence, modify the code in this file directly.