doc: add numpydoc-compliant docstrings to HalfFlat distribution

[KRYSTALM7]

Summary

Adds numpydoc-compliant docstrings to the HalfFlat distribution
in pymc/distributions/continuous.py.

Changes

• Expanded class-level docstring with description and usage example
• Added Parameters and Returns sections to logp method
• Added Parameters and Returns sections to logcdf method

Related Issues

Related to #5459

[welcome]

]
💖 Thanks for opening this pull request! 💖 The PyMC community really appreciates your time and effort to contribute to the project. Please make sure you have read our Contributing Guidelines and filled in our pull request template to the best of your ability.

[read-the-docs-community]

Documentation build overview

📚 pymc | 🛠️ Build #31916472 | 📁 Comparing e430184 against latest (6c48a0b)

🔍 Preview build

Show files changed (17 files in total): 📝 17 modified | ➕ 0 added | ➖ 0 deleted

File	Status
glossary.html	📝 modified
api/generated/pymc.draw.html	📝 modified
api/generated/pymc.icdf.html	📝 modified
api/generated/pymc.logcdf.html	📝 modified
api/generated/pymc.logp.html	📝 modified
api/generated/pymc.sample_posterior_predictive.html	📝 modified
api/generated/pymc.sample_prior_predictive.html	📝 modified
_modules/pymc/distributions/continuous.html	📝 modified
_modules/pymc/distributions/distribution.html	📝 modified
_modules/pymc/logprob/basic.html	📝 modified
_modules/pymc/model/core.html	📝 modified
_modules/pymc/sampling/forward.html	📝 modified
_modules/pymc/smc/sampling.html	📝 modified
api/dims/generated/pymc.dims.HalfFlat.html	📝 modified
api/distributions/generated/pymc.HalfFlat.html	📝 modified
api/distributions/generated/classmethods/pymc.SymbolicRandomVariable.update.html	📝 modified
api/model/generated/classmethods/pymc.model.core.Model.compile_fn.html	📝 modified

[OriolAbril]

There are several unrelated commits being included in the PR. My guess is you started from main and did some changes but now the PR is set to be merged against v6 instead of main.

Regarding the docstring changes themselves. If you look at the docstring for pymc.HalfFlat you'll see only .dist is listed as a method. There is no need to add docstrings to any of its methods. Everything should be documented on the class docstring.

The tutorial linked on the issue you commented on has the following:

You have to review section by section to make sure everything is well documented. If you have chosen a class that is not a distribution, you should review the docstrings of all the methods (only if they already exist though, no need to write missing docstrings). Otherwise, you should work only on the function or class docstring. We will therefore ignore the docstrings of the logcdf, get_moment and dist methods.

This is a distribution so you can ignore the methods.

If you look at some other distributions you'll see they have the extended summary section has the following blocks: formula for the pdf, plot for the pdf and table with support and moments. I think for this one we can skip the plot as it would be a flat line of infinite length and indeterminate y but we can add the other two blocks; in fact, the description of the return value you added to the logp method is basically the pdf formula. As you'll have seen it takes no parameters so you can skip the parameters section in the class docstring.

[KRYSTALM7]

Thank you for the detailed feedback @OriolAbril

I understand the issues I'll update the PR to target main instead of v6,I'll remove the docstrings from logp and logcdf and focus only on the class-level docstring.I will add the PDF formula and support/moments table as seen in other distributions.

Will push the fixes!

Thanks for the Support.

[KRYSTALM7]

@OriolAbril I Updated the PR — removed method docstrings and kept only the
class-level docstring with the pdf formula and support/moments
table.
Please review!

[KRYSTALM7]

@OriolAbril Closing this PR as the branch history got too messy to clean up properly. I've opened a new PR #(will update) with a single clean commit touching only pymc/distributions/continuous.py with the correct class-level docstring. Sorry for the confusion!

[OriolAbril]

@KRYSTALM7 you should start the PR from v6 and target v6 to be merged into. The usual default branch is main but in preparation for a major release the current default is v6 (you can see that by going to the github.com/pymc-devs/pymc repo homepage and looking at which branch is shown)

[KRYSTALM7]

@OriolAbril (#8211) This is a clean replacement for #8208. Sorry for the confusion! I've updated the base branch to v6. The PR is now targeting pymc-devs:v6 as intended. All your feedback has been addressed.Thanks for the patience and guidance. Happy to make any further changes if needed.