athob / py-ananke Goto Github PK

I'm attempting to install py-ananke on my local machine (M2 Mac, OS 13.4, Python 3.11) and the install fails when attempting to build wheels for vaex-core. It seems that vaex-core may not yet support Python 3.11 (see e.g. vaexio/vaex#2331) - perhaps it is best to require Python versions earlier than 3.11 in the py-ananke install until vaex-core fully supports 3.11

The authors have documented the core Ananke class, it's methods and arguments to a high level using docstrings and an accompanying example in a Jupyter notebook. However, all of this documentation exists within the code and is spread across multiple files making it somewhat difficult for a new user to find and read.

I would suggest that the authors start a document named "Documentation" in a user-friendly format (e.g. markdown) and clearly linked from the readme. It should present a brief summary of the relevant API level documentation in one place and in a format that is accessible for users, with instructions/links for where to find further information. As a minimum I believe the document should include the following:

• A high-level description of using py-ananke (i.e. "Create an Ananke pipeline object and call run to return a Galaxia Output survey")
• A link to the jupyter notebook example
• Instructions to view the Ananke class constructor docstring (i.e. "run help(Ananke.__init__)")
• State the expected format of the particles dictionary (as it is in the example)
• Instructions to view the d_params, e_params and err_params options (i.e. "call Ananke.display_density_docs()" etc)
• Instructions to view the Ananke.run docstring (i.e."run help(Ananke.run)")
• A list of the additional kwargs that can be passed to Ananke.run
• Description of the Galaxia.Output data structure in which the output data is returned

If the authors wished to use a more advanced tool like sphinx to incorporate docstrings directly into the documentation that would be excellent but I recognize that would be significantly more work to setup and I'm happy for it to be deferred for future work.