Documentation/15 07 26/sphinx and uml

[MJC598]

What does this PR do?

UML Documentation and some Numpy/SciPy docstring standards.

What Wrike task is this associated with?

https://www.wrike.com/open.htm?id=4509517763

Checklist before merging

• If adding a core feature, I've added related tests.
• This is part of a product update, and I've added an explanation of what is different to the changelog.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

Files with missing lines	Coverage Δ
src/respondpy/_utils.py	100.00% <ø> (ø)
src/respondpy/data/database_helpers.py	100.00% <ø> (ø)
src/respondpy/data/input.py	98.87% <ø> (ø)
src/respondpy/data/logic_conditions.py	100.00% <ø> (ø)
src/respondpy/data/parameters.py	100.00% <ø> (ø)
src/respondpy/data/state_vectors.py	100.00% <ø> (ø)
src/respondpy/data/transition_matrices.py	90.74% <ø> (ø)
src/respondpy/model.py	100.00% <ø> (ø)
src/respondpy/simulation.py	100.00% <ø> (ø)
src/respondpy/transition.py	100.00% <ø> (ø)

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[ddbaptiste]

Question: Should we include the "Returns" field on all docstrings, including those like lines 57-75 in src/respondpy/data/parameters.py:

    def get_parameter_type(self) -> ParameterType:
        """Return the wrapped parameter type."""
        return self.__parameter_type

    def is_time_varying(self) -> bool:
        """Return whether this parameter is indexed by timestep."""
        if self.__parameter_type == ParameterType.INITIAL_COHORT:
            return False
        return True

    def is_transition_matrix_operation(self) -> bool:
        """Return whether this parameter maps to transition-matrix data."""
        if self.__parameter_type in [ParameterType.INTERVENTION_TRANSITION_PROBABILITY, ParameterType.BEHAVIOR_TRANSITION_PROBABILITY]:
            return True
        return False

    def is_state_vector_operation(self) -> bool:
        """Return whether this parameter maps to state-vector data."""
        return not self.is_transition_matrix_operation()

or should we only enforce the documentation in functions that raise errors or return custom types?

Otherwise, just a few small points flagged in line comments.

[MJC598]

Question: Should we include the "Returns" field on all docstrings, including those like lines 57-75 in src/respondpy/data/parameters.py:

    def get_parameter_type(self) -> ParameterType:
        """Return the wrapped parameter type."""
        return self.__parameter_type

    def is_time_varying(self) -> bool:
        """Return whether this parameter is indexed by timestep."""
        if self.__parameter_type == ParameterType.INITIAL_COHORT:
            return False
        return True

    def is_transition_matrix_operation(self) -> bool:
        """Return whether this parameter maps to transition-matrix data."""
        if self.__parameter_type in [ParameterType.INTERVENTION_TRANSITION_PROBABILITY, ParameterType.BEHAVIOR_TRANSITION_PROBABILITY]:
            return True
        return False

    def is_state_vector_operation(self) -> bool:
        """Return whether this parameter maps to state-vector data."""
        return not self.is_transition_matrix_operation()

or should we only enforce the documentation in functions that raise errors or return custom types?

Otherwise, just a few small points flagged in line comments.

I would say we can, although am not entirely sold on things like the standard overloads for Python classes? Doing it for this instance for sure though.