Improving documentation of method by making it dynamically parse into…

… Galaxia's docstring

docs/source/conf.py

@@ -40,6 +40,7 @@
 
 exclude_patterns = ['.ipynb_checkpoints/*']
 
+napoleon_use_param = False
 
 # -- Options for HTML output -------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output

setup.py

@@ -35,7 +35,7 @@
       package_dir={'': SRC_DIR},
       package_data=package_data,
       include_package_data=True,
-      install_requires=["numpy>=1.22,<2", "scipy>=1.7.2,<2", "pandas>=2,<3",
+      install_requires=["numpy>=1.22,<2", "scipy>=1.7.2,<2", "pandas>=2,<3", "docstring_parser>=0.16,<0.17",
                         f"EnBiD_ananke @ file://{(ROOT_DIR / PYENBID).resolve()}",
                         f"Galaxia_ananke @ file://{(ROOT_DIR / PYGALAXIA).resolve()}"]
       )

src/ananke/Ananke.py

@@ -17,6 +17,7 @@
 import Galaxia_ananke as Galaxia
 import Galaxia_ananke.photometry as Galaxia_photo
 
+from . import utils
 from ._constants import *
 from .Universe import Universe
 from .Observer import Observer
@@ -53,7 +54,6 @@ class Ananke:
     _def_uni_rshell = Universe._default_rshell
     _def_photo_sys = Galaxia.DEFAULT_PSYS
     _def_cmd_mags = Galaxia.DEFAULT_CMD
-    _def_cmd_box = Galaxia.DEFAULT_CMD_BOX
     _intrinsic_mag_formatter = '{}_Intrinsic'
     _intrinsic_mag_template = _intrinsic_mag_formatter.format
 
@@ -74,18 +74,18 @@ def __init__(self, particles: Dict[str, NDArray], name: str, ngb: int = 64,
 
             d_params : dict
                 Parameters to configure the kernel density estimation. Use
-                class method display_density_docs to find what parameters can
-                be defined
+                class method ``display_density_docs`` to find what parameters
+                can be defined
 
             e_params : dict
                 Parameters to configure the extinction pipeline. Use class
-                method display_extinction_docs to find what parameters can be
-                defined
+                method ``display_extinction_docs`` to find what parameters can
+                be defined
 
             err_params : dict
                 Parameters to configure the error model pipeline. Use class
-                method display_errormodel_docs to find what parameters can be
-                defined
+                method ``display_errormodel_docs`` to find what parameters can
+                be defined
 
             observer : array-like shape (3,) or dict of array-like shape (3,)
                 Coordinates for the observer in phase space. Position and
@@ -94,67 +94,58 @@ class method display_density_docs to find what parameters can
                 enough. If specifying both position and velocity, please
                 provide a dictionary containing both coordinates as array-like
                 objects of shape (3,), respectively denoting the position and
-                velocity coordinates with keys `{_pos}` and `{_vel}`.
-                Position coordinates default to
-                {_def_obs_position}
-                and velocity coordinates default to
-                {_def_obs_velocity}
+                velocity coordinates with keys ``{_pos}`` and ``{_vel}``.
+                Position coordinates default to::
+                
+                    {_def_obs_position}
+                
+                and velocity coordinates default to::
+                
+                    {_def_obs_velocity}
             
             rshell : array-like shape (2,)
                 Range in kpc of distances from the observer position of the
-                particles that are to be considered. Default to
-                {_def_uni_rshell}.
+                particles that are to be considered. Default to::
+                
+                    {_def_uni_rshell}
 
             photo_sys : string or list
                 Name(s) of the photometric system(s) Galaxia should use to
-                generate the survey. Default to {_def_photo_sys}.
+                generate the survey. Default to ``{_def_photo_sys}``.
                 Available photometric systems can be queried with the class
-                method display_available_photometric_systems.
+                method ``display_available_photometric_systems``.
 
             cmd_magnames : string or dict
                 Names of the filters Galaxia should use for the color-magnitude
                 diagram box selection.
                 The input can be given as string in which case it must meet the
-                following format:
+                following format::
+
                     "band1,band2-band3"
-                where band1 is the magnitude filter and (band2, band3) are the
-                filters that define the band2-band3 color index.
+                
+                where ``band1`` is the magnitude filter and ``(band2, band3)``
+                are the filters that define the ``band2-band3`` color index.
                 Alternatively, a dictionary can be passed with the following
-                format:
+                format::
+
                     dict('magnitude': band1,
                          'color_minuend': band2,
                          'color_subtrahend': band3)
+                
                 The filter names must correspond to filters that are part of
                 the first chosen photometric system in photo_sys. Default to
-                {_def_cmd_mags}.
-                
-            app_mag_lim_lo : float
-            app_mag_lim_hi : float
-            abs_mag_lim_lo : float
-            abs_mag_lim_hi : float
-            color_lim_lo : float
-            color_lim_hi : float
-                These allow to specify the limits of the chosen color-magnitude
-                diagram box selection (lo for lower and hi for upper). app_mag,
-                abs_mag and color represent respectively limits in apparent
-                magnitudes, absolute magnitudes and color index. Default values
-                follow those set in:
-                {_def_cmd_box}.
-
-            fsample : float
-                Sampling rate from 0 to 1 for the resulting synthetic star
-                survey. 1 returns a full sample while any value below returns
-                partial surveys. Default to 1.
+                ``'{_def_cmd_mags}'``.
+            {parameters_from_galaxia}
             
             Notes
             -----
-            The input particles must include same-length arrays for every key of
-            the list of keys return by property required_particles_keys.
-            Particular attention should be given to arrays of keys '{_pos}' and
-            '{_vel}' that must be shaped as (Nx3) arrays of, respectively,
-            position and velocity vectors. Use the class method
-            make_dummy_particles_input to generate a dummy example of such input
-            dictionary.
+            The input particles must include same-length arrays for every key
+            of the list of keys return by property required_particles_keys.
+            Particular attention should be given to arrays of keys ``'{_pos}'``
+            and ``'{_vel}'`` that must be shaped as (Nx3) arrays of,
+            respectively, position and velocity vectors. Use the class method
+            ``make_dummy_particles_input`` to generate a dummy example of such
+            input dictionary.
         """
         self.__particles: Dict[str, NDArray] = particles
         self.__name: str = name
@@ -174,8 +165,13 @@ class method display_density_docs to find what parameters can
                                                _def_obs_velocity=_def_obs_velocity,
                                                _def_uni_rshell=_def_uni_rshell,
                                                _def_photo_sys=_def_photo_sys,
+                                               parameters_from_galaxia = utils.extract_parameters_from_docstring(
+                                                   Galaxia.Survey.make_survey.__doc__,
+                                                   parameters=[
+                                                       'fsample',
+                                                       'app_mag_lim_lo, app_mag_lim_hi, abs_mag_lim_lo, abs_mag_lim_hi, color_lim_lo, color_lim_hi'
+                                                    ]).replace("\n", "\n            "),
                                                _def_cmd_mags=_def_cmd_mags,
-                                               _def_cmd_box=_def_cmd_box,
                                                _pos=_pos, _vel=_vel)
 
     def _prepare_universe_proxy(self, kwargs: Dict[str, Any]) -> Universe:
@@ -231,8 +227,7 @@ def _run_galaxia(self, rho, **kwargs) -> Galaxia.Output:
                 A dictionary of same-length arrays representing kernel density
                 estimates for the pipeline particles
 
-            input_dir : string
-            output_dir : string
+            input_dir, output_dir : string
                 Optional arguments to specify paths for the directories where
                 ananke should generate input and output data.
                 
@@ -245,10 +240,7 @@ def _run_galaxia(self, rho, **kwargs) -> Galaxia.Output:
             surveyname : string
                 Optional name Galaxia should use for the output files. Default
                 to 'survey'.
-
-            **kwargs
-                Additional parameters used by the method make_survey of
-                Galaxia's Survey objects
+            {parameters_from_galaxia}
 
             Returns
             -------
@@ -260,7 +252,14 @@ def _run_galaxia(self, rho, **kwargs) -> Galaxia.Output:
         self.__galaxia_output: Galaxia.Output = survey.make_survey(**self._galaxia_kwargs, **kwargs)
         return self._galaxia_output
 
-    _run_galaxia.__doc__ = _run_galaxia.__doc__.format(POS_TAG=POS_TAG, VEL_TAG=VEL_TAG)
+    _run_galaxia.__doc__ = _run_galaxia.__doc__.format(POS_TAG=POS_TAG, VEL_TAG=VEL_TAG,
+                                                       parameters_from_galaxia = utils.extract_parameters_from_docstring(
+                                                           Galaxia.Survey.make_survey.__doc__,
+                                                           ignore=[
+                                                               'fsample', 'cmd_magnames', 'parfile', 'output_dir',
+                                                               'rSun0, rSun1, rSun2', 'vSun0, vSun1, vSun2', 'r_max, r_min',
+                                                               'app_mag_lim_lo, app_mag_lim_hi, abs_mag_lim_lo, abs_mag_lim_hi, color_lim_lo, color_lim_hi'
+                                                            ]).replace("\n", "\n            "))
 
     @classmethod
     def __pp_observed_mags(cls, df: pd.DataFrame, mag_names, _dmod) -> None:
@@ -292,27 +291,12 @@ def run(self, **kwargs) -> Galaxia.Output:
             
             Parameters
             ----------
-            input_dir : string
-            output_dir : string
-            i_o_dir : string
+            input_dir, output_dir, i_o_dir : string
                 Optional arguments to specify paths for the directories where
                 ananke should generate input and output data. If the i_o_dir
                 keyword argument is provided, it overrides any path given to
                 the input_dir and output_dir keyword arguments.
-
-            k_factor : float
-                Scaling factor applied to the kernels lengths to adjust all
-                the kernels sizes uniformly. Lower values reduces the kernels
-                extents, while higher values increases them.
-                Default to 1 (no adjustment).
-                 
-            surveyname : string
-                Optional name Galaxia should use for the output files. Default
-                to 'survey'.
-
-            **kwargs
-                Additional parameters used by the method make_survey of
-                Galaxia's Survey objects
+            {parameters_from_run_galaxia}
 
             Returns
             -------
@@ -326,6 +310,11 @@ def run(self, **kwargs) -> Galaxia.Output:
         self._pp_errors()
         return galaxia_output
 
+    run.__doc__ = run.__doc__.format(
+        parameters_from_run_galaxia = utils.extract_parameters_from_docstring(
+            _run_galaxia.__doc__,
+            ignore=['input_dir, output_dir', 'rho']).replace("\n", "\n            "))
+
     @property
     def _densitiesdriver_proxy(self) -> DensitiesDriver:
         return self.__densitiesdriver_proxy
@@ -519,7 +508,7 @@ def display_density_docs(cls) -> None:
     @classmethod
     def display_EnBiD_docs(cls) -> None:
         """
-            Print the EnBiD.run_enbid docstring
+            Print the EnBiD.run_enbid method docstring
         """
         DensitiesDriver.display_EnBiD_docs()
 
@@ -537,6 +526,13 @@ def display_errormodel_docs(cls) -> None:
         """
         print(ErrorModelDriver.__init__.__doc__)
 
+    @classmethod
+    def display_galaxia_makesurvey_docs(cls) -> None:
+        """
+            Print the Galaxia.Survey.make_survey method docstring
+        """
+        print(Galaxia.Survey.make_survey.__doc__)
+
 
 Ananke.make_dummy_particles_input.__func__.__doc__ = Ananke.make_dummy_particles_input.__doc__.format(
     dummy_dictionary_description=Ananke.make_dummy_dictionary_description())

src/ananke/utils.py

@@ -2,11 +2,14 @@
 """
 Module miscellaneous utilities
 """
+from typing import Optional, List
+import re
+import docstring_parser as DS_parser
 import pandas as pd
 
 from Galaxia_ananke import utils as Gutils
 
-__all__ = ['compare_given_and_required', 'confirm_equal_length_arrays_in_dict', 'RecordingDataFrame']
+__all__ = ['compare_given_and_required', 'confirm_equal_length_arrays_in_dict', 'RecordingDataFrame', 'extract_parameters_from_docstring']
 
 
 compare_given_and_required = Gutils.compare_given_and_required
@@ -38,3 +41,14 @@ def __getitem__(self, key):
     @property
     def record_of_all_used_keys(self):
         return self._record_of_all_used_keys
+
+
+def extract_parameters_from_docstring(docstring: str, parameters: Optional[List[str]] = None, ignore: Optional[List[str]] = None) -> str:
+    input_DS = DS_parser.parse(docstring)
+    output_DS = DS_parser.Docstring()
+    output_DS.style = input_DS.style
+    output_DS.meta = [param
+                      for param in input_DS.params
+                      if (True if parameters is None else param.arg_name in parameters) and (True if ignore is None else param.arg_name not in ignore)]
+    temp_docstring = re.split("\n-*\n",DS_parser.compose(output_DS),maxsplit=1)[1]
+    return '\n'.join([line if line[:1] in ['', ' '] else f"\n{line}" for line in temp_docstring.split('\n')])