PertSpace docs improvements

[Lilly-May]

PR Checklist

• Documentation in docs is updated

Description of changes

While skimming the PertSpace documentation, I observed that the documentation could benefit from minor improvements. Specifically, I did the following:

• Corrected example formatting (e.g., identified broken formatting here).
• Ensured that all PertSpace methods specify the return type and include a description of what they return, if applicable.
• Added explanations for some missing parameters.
• Switch to pandas.DataFrame.iloc for index based selection to silence FutureWarning

[codecov]

Codecov Report

Attention: 2 lines in your changes are missing coverage. Please review.

Comparison is base (63217f7) 62.92% compared to head (e066504) 62.92%.

Additional details and impacted files

@@           Coverage Diff           @@
##             main     #471   +/-   ##
=======================================
  Coverage   62.92%   62.92%           
=======================================
  Files          41       41           
  Lines        4637     4637           
=======================================
  Hits         2918     2918           
  Misses       1719     1719           

Files	Coverage Δ
pertpy/tools/_perturbation_space/_clustering.py	97.36% <ø> (ø)
...y/tools/_perturbation_space/_perturbation_space.py	85.79% <ø> (ø)
pertpy/tools/_perturbation_space/_simple.py	75.22% <ø> (ø)
...s/_perturbation_space/_discriminator_classifier.py	90.25% <0.00%> (ø)

[Zethson]

Lovely!