DOC: api.py, docstring improvements

[josef-pkt]

more docstrings #7564
and api cleanup in stats #7013
The two issues are not finished by this PR, still some problems left

this includes now some additions to api.rst, and some reordering init by topic

[lgtm-com]

This pull request introduces 10 alerts when merging 0408b6f into 2e07422 - view on LGTM.com

new alerts:

• 8 for Unused import
• 1 for Explicit export is not defined
• 1 for Implicit string concatenation in a list

[josef-pkt]

Cleanup of module namespaces didn't work (I thought I had done this in the (distant) past)
del names at end of module, deletes them from the runtime environment, and breaks functions
e.g. https://stackoverflow.com/questions/30040658/delete-modules-to-clean-namespace

In my notebook I only imported the modules to check available names. I didn't run any functions. That works without problems.

(initially posted to wrong issue)

[josef-pkt]

checking module name finds imports, e.g.

m = [i for i in m if not getattr(getattr(module, i), "__module__", None) == module.__name__]

but has false positives, if a function is written in another module, but the current module is the "official" public module for it.

[josef-pkt]

I removed all the del at end of modules again, amended and force pushed to clean commit

I still have a few functions missing in api.py for which I'm not sure about whether or how to add them, e.g. knockoff_effects and outlier_influence

[josef-pkt]

related aside: formula.api has del at the end of the module to clean namespace. But it doesn't have functions defined in the module, so there are no problems.

[lgtm-com]

This pull request introduces 10 alerts when merging ce21816 into 2e07422 - view on LGTM.com

new alerts:

• 8 for Unused import
• 1 for Explicit export is not defined
• 1 for Implicit string concatenation in a list

[josef-pkt]

merge when green

I will do another round later

[bashtage]

WARNING: [autosummary] failed to import 'statsmodels.distributions.copula.api.ArchimedeanCopula': no module named statsmodels.distributions.copula.api.ArchimedeanCopula
WARNING: [autosummary] failed to import 'statsmodels.distributions.copula.api.ClaytonCopula': no module named statsmodels.distributions.copula.api.ClaytonCopula
WARNING: [autosummary] failed to import 'statsmodels.distributions.copula.api.CopulaDistribution': no module named statsmodels.distributions.copula.api.CopulaDistribution
WARNING: [autosummary] failed to import 'statsmodels.distributions.copula.api.ExtremeValueCopula': no module named statsmodels.distributions.copula.api.ExtremeValueCopula
WARNING: [autosummary] failed to import 'statsmodels.distributions.copula.api.FrankCopula': no module named statsmodels.distributions.copula.api.FrankCopula
WARNING: [autosummary] failed to import 'statsmodels.distributions.copula.api.GaussianCopula': no module named statsmodels.distributions.copula.api.GaussianCopula
WARNING: [autosummary] failed to import 'statsmodels.distributions.copula.api.GumbelCopula': no module named statsmodels.distributions.copula.api.GumbelCopula
WARNING: [autosummary] failed to import 'statsmodels.distributions.copula.api.IndependenceCopula': no module named statsmodels.distributions.copula.api.IndependenceCopula
WARNING: [autosummary] failed to import 'statsmodels.distributions.copula.api.StudentTCopula': no module named statsmodels.distributions.copula.api.StudentTCopula

[bashtage]

I think you need to link to the actual location that is used in the docs, not the API version.

[bashtage]

Also see

/home/runner/work/statsmodels/statsmodels/docs/source/examples/index.rst:394: WARNING: toctree contains reference to nonexisting document 'examples/notebooks/generated/copula'

Is notebook working correctly?

[lgtm-com]

This pull request introduces 12 alerts when merging c89bcda into 20082ce - view on LGTM.com

new alerts:

• 10 for Unused import
• 1 for Explicit export is not defined
• 1 for Implicit string concatenation in a list

[josef-pkt]

something strange
notebook and using copula.api in docs works in main
dev html docs look correct

[josef-pkt]

Import error, I made a mistake and didn't run the distribution tests locally.
(I was only paying attention to stats)

[bashtage]

Can you add an __all__ to get rid of the unused import messages?

[josef-pkt]

problem/type with singular or plural names, I might have to rename a module
depfuncs_ev versus depfunc_ev
for transforms I used plural

[josef-pkt]

@bashtage

why does LGTM ignore pylint and flake options in module?

# pylint: disable=W0611
# flake8: noqa

which satisfies the azure style check in copulas.api

[bashtage]

Why not just add to __all__ which is the correct approach?

[josef-pkt]

Why not just add to all which is the correct approach?

because it's a pain to maintain and it is never used.

[bashtage]

It is used by ipython.

…

On Tue, Sep 21, 2021, 17:13 Josef Perktold ***@***.***> wrote: Why not just add to *all* which is the correct approach? because it's a pain to maintain and it is never used. — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#7732 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/ABKTSRO5YS3NPBHNJT2BTYTUDCVL5ANCNFSM5EMROAXQ> . Triage notifications on the go with GitHub Mobile for iOS <https://apps.apple.com/app/apple-store/id1477376905?ct=notification-email&mt=8&pt=524675> or Android <https://play.google.com/store/apps/details?id=com.github.android&referrer=utm_campaign%3Dnotification-email%26utm_medium%3Demail%26utm_source%3Dgithub>.

[lgtm-com]

This pull request introduces 3 alerts when merging bf946d3 into 20082ce - view on LGTM.com

new alerts:

• 3 for Unused import

[josef-pkt]

another false alarm in docs:

the links to the two other notebooks work correctly in the dev html docs

/home/runner/work/statsmodels/statsmodels/docs/source/examples/notebooks/generated/formulas.ipynb:201: WARNING: File not found: 'examples/notebooks/generated/regression_diagnostics.html'
/home/runner/work/statsmodels/statsmodels/docs/source/examples/notebooks/generated/formulas.ipynb:498: WARNING: File not found: 'examples/notebooks/generated/contrasts.html'

I have one mistake in api.rst, wrong path to model
and one more missing function in stats.api.__all__

[lgtm-com]

This pull request fixes 8 alerts when merging 6f18ef0 into 20082ce - view on LGTM.com

fixed alerts:

• 8 for Unused import