Improved documentation layout for algorithm class

[MargaretDuff]

Description

Closes #1793

Looks better

Help on class Algorithm in module cil.optimisation.algorithms.Algorithm:

class Algorithm(builtins.object)
 |  Algorithm(update_objective_interval=1, max_iteration=None, log_file=None)
 |  
 |  Base class for iterative algorithms that provides the minimal infrastructure.
 |  
 |  Algorithms are iterables so can be easily run in a for loop. They will stop as soon as the stop criterion is met.
 |  The user is required to implement the :code:`set_up`, :code:`__init__`, :code:`update` and :code:`update_objective` methods.
 |  
 |  The method :code:`run` is available to run :code:`n` iterations. The method accepts a :code:`callbacks` list of callables, each of which receive the current Algorithm object (
which in turn contains the iteration number and the actual objective value) and can be used to trigger print to screens and other user interactions. The :code:`run` method will st
op when the stopping criterion is met or `StopIteration` is raised.
 |  
 |  Parameters
 |  ----------
 |  update_objective_interval: int, optional, default 1
 |      the interval every which we would save the current objective. 1 means every iteration, 2 every 2 iteration and so forth. This is by default 1 and should be increased when 
evaluating the objective is computationally expensive.
 |  
 |  Methods defined here:
 |  
 |  __init__(self, update_objective_interval=1, max_iteration=None, log_file=None)
 |      Initialize self.  See help(type(self)) for accurate signature.
 |  
 |  __iter__(self)
 |      Algorithm is an iterable
 |  
 |  __next__(self)
 |      Algorithm is an iterable
 |      
 |      This method triggers :code:`update()` and :code:`update_objective()`
 |  
 |  get_last_loss(self, return_all=False)
 |      Returns the last stored value of the loss function. If `update_objective_interval` is 1 it is the value of the objective at the current iteration. If update_objective_inte
rval > 1 it is the last stored value.
 |      Returns
 |      -------
 |      Float
 |          Last stored value of the loss function
 |  
 |  get_last_objective = get_last_loss(self, return_all=False)
 |  
 |  get_output(self)
 |      Returns the current solution.
 |  
 |  is_provably_convergent(self)
 |      Check if the algorithm is convergent based on the provable convergence criterion.
 |      
 |      Returns
 |      -------
 |      Boolean
 |          Outcome of the convergence check
|  
 |  max_iteration_stop_criterion(self)
 |      Do not use: this is being deprecated
 |  
 |  objective_to_dict(self, verbose=False)
 |      Internal function to save and print objective functions
 |  
 |  objective_to_string(self, verbose=False)
 |      Do not use: this is being deprecated
 |  
 |  run(self, iterations=None, callbacks: Optional[List[cil.optimisation.utilities.callbacks.Callback]] = None, verbose=1, **kwargs)
 |      run upto :code:`iterations` with callbacks/logging.
 |      
 |      For a demonstration of callbacks see https://github.com/TomographicImaging/CIL-Demos/blob/main/misc/callback_demonstration.ipynb
 |      
 |      Parameters
 |      -----------
 |      iterations: int, default is None
 |          Number of iterations to run. If not set the algorithm will run until :code:`should_stop()` is reached
 |      callbacks: list of callables, default is Defaults to :code:`[ProgressCallback(verbose)]`
 |          List of callables which are passed the current Algorithm object each iteration. Defaults to :code:`[ProgressCallback(verbose)]`.
 |      verbose: 0=quiet, 1=info, 2=debug
 |          Passed to the default callback to determine the verbosity of the printed output.
 |  
 |  set_up(self, *args, **kwargs)
 |      Set up the algorithm
 |  
 |  should_stop(self)
 |      default stopping criterion: number of iterations
 |      
 |      The user can change this in concrete implementation of iterative algorithms.
 |  
 |  update(self)
 |      A single iteration of the algorithm
 |  
 |  update_objective(self)
 |      calculates the objective with the current solution
 |  
 |  verbose_header(self, *_, **__)
 |      Do not use: this is being deprecated
 |  
 |  verbose_output(self, *_, **__)
 |      Do not use: this is being deprecated
 |  
 |  ----------------------------------------------------------------------
 |  Readonly properties defined here:
 |  
 |  iterations
 |      returns the iterations at which the objective has been evaluated
 |  
 |  loss
 |      returns the list of the values of the objective during the iteration
     
 |      The length of this list may be shorter than the number of iterations run when the update_objective_interval > 1
 |  
 |  objective
 |      returns the list of the values of the objective during the iteration
 |      
 |      The length of this list may be shorter than the number of iterations run when the update_objective_interval > 1
 |  
 |  solution
 |      Returns the current solution.
 |  
 |  ----------------------------------------------------------------------
 |  Data descriptors defined here:
 |  
 |  __dict__
 |      dictionary for instance variables (if defined)
 |  
 |  __weakref__
 |      list of weak references to the object (if defined)
 |  
 |  max_iteration
 |      gets the maximum number of iterations
 |  
 |  update_objective_interval
 |      gets the update_objective_interval

Checklist

• I have performed a self-review of my code
• I have added docstrings in line with the guidance in the developer guide
• I have updated the relevant documentation
  - [ ] I have implemented unit tests that cover any new or modified functionality
• CHANGELOG.md has been updated with any functionality change
• Request review from all relevant developers
• Change pull request label to 'Waiting for review'

Contribution Notes

Please read and adhere to the developer guide and local patterns and conventions.

• The content of this Pull Request (the Contribution) is intentionally submitted for inclusion in CIL (the Work) under the terms and conditions of the Apache-2.0 License
• I confirm that the contribution does not violate any intellectual property rights of third parties

[MargaretDuff]

[jakobsj]

Very nice improvements to layout and contents of algorithm documentation. I added a few further suggestions.

[jakobsj]

Thank you, the description reads well!

[lauramurgatroyd]

Looks great, just added some minor comments

[lauramurgatroyd]

Looks great, thanks!

[MargaretDuff]

Jenkins is happy