Update doc comments, typehinting, and code structure

[WYVERN2742]

As part of the software sustainability hackathon, efforts are ongoing to make CIL easier to use for users and developers.

This issue is focused on improving the python code documentation with Numpy-style docstrings, modern python typehinting, and following a standard format for class structure.

'Standards' followed:

• Using Numpy's doc format for python

  • If the function has typehints, omit type hinting from the docstring:

    def __init__(self, input:AcquisitionData, image_geometry:Optional[ImageGeometry]=None, backend="tigre"):
        """Abstract class for a tomographic reconstructor.
    
        Parameters
        ----------
        input
            Input data for reconstruction
        image_geometry
            Image geometry of input data, by default None
        backend
            Engine backend used for reconstruction, by default "tigre"
    
        Raises
        ------
        TypeError
            Raised if input data is not an AcquisitionData class
        """

  • Private functions do not need to be documented (they are for developer internal use)
• Class Structure (basically an inverse of c):
  1. __init__
     • Init is first due to its documentation existing in the class's docstring, and properties may be large
  2. Properties
  3. Static functions
  4. Functions
  5. Private functions
  6. Special functions (__str__())
• Use " for strings (May change later on, but uniformity is good)
• Use relative imports from cil.framework.recon import Reconstructor -> from .Reconstructor import Reconstructor to fix circular packaging issues #1681

There are still ongoing talks for enforcing a code style with a formatter, as such this issue ignores code style, and focuses on class order and doc comments.

Note: this change doesn't include functional changes that have been discussed:

• Functions should return out if passed in, not None #1657

---

Progress:

cil/

• [ ] framework/ - Waiting for #1686
• [ ] io/
• [ ] optimisation/
• [ ] plugins/
  • [ ] astra/ 🟡 Waiting for Review #1697
  • [ ] ccpi_registration/
  • [ ] tigre/
  • [ ] TomoPhantom.py
• [ ] processors/
• [ ] recon/ 🟡 Waiting for Review #1685
• [ ] utilities/

[WYVERN2742]

Note: This does depend on #1686 to be merged, and then another pass to ensure typing compatabillity across CIL to finally pass static checkers