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:
Espresso core#
How to modify EspressoProblem base class#
Modify the class in file
src/espresso/espresso_problem.py
Make sure your changes are backward compatible, otherwise take the responsibility of modifying existing contributions under folder
contrib/
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
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
.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#
Add the exception in file
src/espresso/exceptions.py
.Add docstring inside the class itself, and add its name to the docstring of the super class
EspressoError
.Add new exception into the list in file
docs/source/_templates/exception.rst
.
How to add a new utility function#
Add the function in folder
src/espresso/utils/
.Write docstring for the function.
Import and add the name to
__all__
variable fromsrc/espresso/utils/__init__.py
.Add the name into docstring at top of
src/espresso/utils/__init__.py
.
Espresso machine#
How to modify build/validation scripts#
Navigate to
espresso_machine/build_package/
folder, all the scripts are there. Make changes as you need.Ensure the other scripts still work. For example, you might want to change usage of
validate.py
insidebuild.py --validate
after the argument parser is modified. Check by running them on your own.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#
To build the documentation, run the following under the
docs/
folder:$ make html
To serve the website locally:
$ python -m http.server 8000 -d build/html
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/
anddocs/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.