Document method wrappers which transform the `auto` value for a parameter

Open Beginner friendly
#547 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Assessment

Difficulty
2/5
Estimated time
1-3 hours
Newbie friendliness
68/100
Issue type
Documentation
Clarity
Clearly specified
Activity status
Stale
Tech stack
python
Domain
documentation

Research direction

Start by reading httomo/method_wrappers/dezinging.py around lines 51–58 and httomo/method_wrappers/generic.py around lines 264–269. Identify the wrappers that accept auto for axis and document how each transforms it before calling the underlying method. Done means the wrapper documentation clearly explains the YAML value and the resulting method parameter type.

Written by the indexing model from the issue text.

Description

documentation

The auto value can be used for a few different parameters of different methods, such as:

The underlying methods from their respective libraries have the axis parameter which don't have auto as a possible value, but in httomo YAML pipeline config files we have introduced the ability to override the value of this axis parameter and have the associated wrapper transform the "auto" into something else on behalf of the users.

This results in the YAML config file for a method using the auto value presenting a different public API compared to the public API of the method function in its respective library (ie, its type signature): in httomo, the value of axis is presented to be able to be auto, but in the method function itself, the value of axis is an int. These will have different types:

  • allowing axis to have a value of auto in addition to integers will have the type Union[Literal["auto"], int]
  • allowing axis to only have an integer value will have type int

The method wrappers doing this transformation from auto to an int (which form the perspective of types is a conversion from a Union[Literal["auto"], int] to an int) aren't documented as doing so.

Documenting the method wrappers to at least have some information about the transformation being done can help mitigate confusion regarding the two conflicting public API's that are exposed by httomo's YAML config files vs. the method function's documentation.

Dominant language
Python
Stars
10
Forks
5
Avg merge
5d 17h
Merged PRs (30d)
1

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from DiamondLightSource/httomo

All issues in DiamondLightSource/httomo

Similar issues

More Python issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.