===============
Developer Notes
===============

🚧 This page is under construction. 

Please `contact us <../user_guide/faq.html>`_ directly if you have questions.

How-to Guides
=============

.. contents::
    :local:


Build the package locally
-------------------------

Check out the `contributor guide  <../contributor_guide/new_contrib.html>`_.


Build the documentation locally
-------------------------------

Check out README file under docs folder 
`here <https://github.com/inlab-geo/espresso/tree/main/docs/README.md>`_.


Modify EspressoProblem class
----------------------------

1. Modify the class in file :code:`src/espresso/espresso_problem.py`
2. Make sure your changes are backward compatible, otherwise take the responsibility of
   modifying existing contributions under folder :code:`contrib/`
3. Make new contribution generation script compatible with new changes. Check by running 
   file :code:`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 :code:`espresso_machine/new_contribution/_template`. Pay special 
     attention to the following files:

     - :code:`espresso_machine/new_contribution/_template/example_name.py`
     - :code:`espresso_machine/new_contribution/_template/README.md`

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

   - :code:`espresso_machine/build_package/validate.py --pre`
   - :code:`espresso_machine/build_package/build.py`
   - :code:`espresso_machine/build_package/validate.py --post`
   - :code:`espresso_machine/build_package/build.py --validate`
   
   Examine reported error (if any) to locate whether to change scripts themselves, or to
   edit the template files under :code:`espresso_machine/new_contribution/_template`.

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

   - :code:`README.md`
   - :code:`docs/source/user_guide/introduction.rst`
   - :code:`docs/source/contributor_guide/new_contrib.rst`
   - :code:`espresso_machine/new_contribution/_template/README.md`


Modify build/validation scripts
-------------------------------

1. Navigate to :code:`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 :code:`validate.py`
   inside :code:`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:

   - :code:`espresso_machine/README.md`
   - :code:`espresso_machine/new_contribution/_template/README.md`
   - :code:`docs/source/contributor_guide/new_contrib.rst`


Add a new EspressoError
-----------------------

1. Add the exception in file :code:`src/espresso/exceptions.py`.
2. Add docstring inside the class itself, and add its name to the docstring of the 
   super class :code:`EspressoError`.
3. Add new exception into the list in file :code:`docs/source/_templates/exception.rst`.


Add a new utility function
--------------------------

1. Add the function in folder :code:`src/espresso/utils/`.
2. Write docstring for the function.
3. Import and add the name to :code:`__all__` variable from :code:`src/espresso/utils/__init__.py`.
4. Add the name into docstring at top of :code:`src/espresso/utils/__init__.py`.


Change layout of problem-specific documentation
-----------------------------------------------

This refers to the 
`pages for each contribution problem <https://geo-espresso.readthedocs.io/en/latest/user_guide/contrib/index.html>`_.
These pages are dynamically generated by :code:`docs/source/_ext/generate_contrib_docs.py`.
To change the layout of README, metadata and licence, modify the code in this file directly.
