gempyor API docstring refurbishment
#468
Open
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
…mprzy/flepiMoP into gempyor-docstring-improvements
TimothyWillard
added
gempyor
TimothyWillard
requested changes
Jan 24, 2025
There was a problem hiding this comment.
Overall looks good, I think an improvement over the current state. A few themes:
- What's up with putting the file name as the header of a module docstrings? Seems redundant.
- There are some typing signatures that are off, I'd rather have no type signature than an incorrect one so if it's not clear let's leave it for another PR.
- There were some docstrings of CLI commands that were edited in ways that I think will look off when using
--help, I think we need to be careful about not applying the same docstring style to click commands.
Comment on lines
152
to
170
| """ | ||
| Calibrate using an `emcee` sampler to initialize a model based on a config. | ||
|
|
||
| Args: | ||
| config_filepath: Path to the configuration file. | ||
| project_path: Path to the project directory. | ||
| nwalkers: Number of walkers (MCMC chains) to run. | ||
| niter: Number of MCMC iterations to perform. | ||
| nsamples: Number of samples to select from final MCMC chain. | ||
| nthin (optional): How often to save samples. | ||
| ncpu: Number of CPU cores to use for parallelization. | ||
| input_run_id (optional): Run ID. Will be auto-generated if not provdied. | ||
| prefix (optional): A prefix for output files. | ||
| resume: Whether or not to resume a previous calibration run. | ||
| resume_location (optional): Path to the location of the saved state to resume from. | ||
|
|
||
| Returns: | ||
| None | ||
| """ |
There was a problem hiding this comment.
Generally, this is good docs! However, because this is a click CLI command it's going to look very strange in terminal (try doing flepimop-calibrate --help to see what I mean).
There was a problem hiding this comment.
Mmm yes, looks weird. So should I delete the Args and returns section and just leave the description sentence?
|
This PR can also be used to address GH #431 . |
…mprzy/flepiMoP into gempyor-docstring-improvements
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Describe your changes.
This pull request:
gempyorgempyor, it does not propagate poor documentationAs I see it, the
gempyorAPI mainly consists of:ModelInfoclass frommodel_info.pyParametersclass fromparameters.py, and some associated methodsGempyorInferenceclass frominference.py, and some associated methodsCompartmentsclass fromcompartments.py, and some associated methodsutils.py(read_dfandwrite_df)Note, before narrowing my focus on guidance from Carl, I also wrote some docstring in two files (
calibrate.pyandcli.py). I do not think of these as being integral parts of thegempyorAPI, but because I worked on them in in the same sweep of work that I worked on the others, they are also included in this PR with some docstring improvements.What does your pull request address? Tag relevant issues.
This pull request addresses GH #462.