How-to guides

How-to guides#

Contents

Getting ready#

How to get started with developing Espresso#

Before you work on any parts of Epsresso, make sure you have the project forked and cloned, and a development environment prepared.

If not, follow these pages before you continue with the development:

  1. Contributor guide - GitHub setup

  2. Contributor guide - environment setup

Espresso core#

How to modify EspressoProblem base class#

  1. Modify the class in file src/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 espresso_machine/new_contribution/create_new_contrib.py.

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

      • espresso_machine/new_contribution/_template/example_name.py

      • espresso_machine/new_contribution/_template/README.md

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

    • espresso_machine/build_package/validate.py --pre

    • espresso_machine/build_package/build.py

    • espresso_machine/build_package/validate.py --post

    • espresso_machine/build_package/build.py --pre --post

    Examine reported error (if any) to locate whether to change scripts themselves, or to edit the template files under espresso_machine/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

How to add a new EspressoError#

  1. Add the exception in file src/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.

How to add a new utility function#

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

  2. Write docstring for the function.

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

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

Espresso machine#

How to modify build/validation scripts#

  1. Navigate to espresso_machine/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.py --validate 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:

    • espresso_machine/README.md

    • docs/source/contributor_guide/new_contrib.rst

Documentation#

How to build the documentation locally#

  1. To build the documentation, run the following under the docs/ folder:

    $ make html

  2. To serve the website locally:

    $ python -m http.server 8000 -d build/html

  3. Open localhost:8000 in your browser.

How to edit the documentation#

Folder docs/source contains all the text files for this documentation:

  • docs/source/conf.py has all the configurations for this documentation, including the theme, extensions, title, where templates are, what to exclude / include when building the documentation, etc.

  • docs/source/index.rst corresponds to the home page, in which you can see the source of the introductory paragraph, 4 panels in the home page and the table of contents.

  • docs/source/user_guide/, docs/source/contributor_guide/ and docs/source/developer_notes contain the other documentation pages.

How to change layout of Test Problems Reference#

If you want to change the auto-generated Test Problems Reference page, modify the Python script espresso_machine/doc_utils/gen_docs.py. In the backend, functions in this file is called by docs/source/_ext/generate_contrib_docs.py as a part of builder-inited plugin when building the documentation.