Packaging To Do

[evavagiakis]

• Top level directory should be cleaner (move physics to inner dir)
  • the TLD should contain only the following files (plus folders, see next list)
    • LICENSE.txt there are a limited number of possibilities for this; feel free to copy whatever seems most appropriate
    • README.md this is by default the "greeting" material on the GitHub page, so it should use markdown and include installation and usage instructions
    • pyproject.toml includes dependencies, version info, etc. (this mostly replaces setup.py in case you're more familiar with that)
    • setup.cfg (optional) this can take some of the data from pyproject.toml in case you want to split it up
    • conda-env.yml (optional) this is a very handy way to help people create their own new venv that will work with your code
  • the TLD should contain the following folders, which themselves contain the working bits
    • an inner / working / main directory with the same name as the TLD (but in strictly lower case) into which all physics modules go
    • tests inside of which there are modules whose names start "test_" and mimic the modules in the working directory
    • paper inside of which the JOSS materials go
    • notebooks (optional, but you will want this)
    • .github/workflows (optional, but this will contain the CI script for making a JOSS pdf draft)
• Clean up unused functions in notebook + modules [Sam will break out] {<-- not going to do this quite yet, since I'm not sure which modules are being used -Sam}
• Make the start/end of the different parts of the notebook clearer (Making distribution vs Running sims using them)
  • the most up-to-date (eg, the last month or so) version of jupyter-notebook includes some very nice new capability for nesting sections using markdown -- consider using this new functionality
  • have a title section including a short, descriptive title for the notebook, the name of the creator, and the date it was created
  • break up sections (with titles) according to the important functions whose use you want to demonstrate
  • the explanation at the top is good, but I'd like more annotation and notes throughout! I think I have comments before every calculation cell. This can be very colloquial
• documentation should be improved and standardized throughout! The standard is called sphinx in case you want to google it. If you have a IDE then it might do this automatically (PyCharm does; I believe VSCode does as well). I don't know how particular you need to be, but you should at least have two separate "sections", one called Args: or Inputs: or Parameters: and another called Returns:. There should be a clear demarcation between these sections. The docstring should essentially be pseudo-code that is sufficiently detailed that someone could rewrite the function using only the docstring (if they had to). You don't need to document "hidden" functions (functions that start with _) -- in fact, if you find yourself looking at a function and you think "this doesn't really need to be documented since I don't think a user will need to interact with it directly", that's an indication that maybe it ought to be a hidden function

For all of this, there should be decent examples in DeepCMBsim