ConorMacBride commented 3 years ago

Implements two new options for enabling the documenting of private and/or special methods. Only enabled for class names listed in config file. Class names must be given in full, e.g.,module.submodule.classname. These options are useful for including private/special methods of base classes in documentation intended for new developers. This helps a new developer quickly create a new subclass, which makes use of, or overrides, private methods in the base class.

automodsumm_private_methods_of Should be a list of fully qualified names of classes where all of its private methods (i.e., method names beginning with an underscore, but not ending with a double underscore) should be documented. Defaults to [].
automodsumm_special_methods_of Should be a list of fully qualified names of classes where all of its special methods (i.e., method names beginning with a double underscore and ending with a double underscore) should be documented. Defaults to [].

Two new test cases are included, ensuring that each option only includes methods (either private or special) for the specified class names. Also ensures that the new options do not enable in the inclusion of extra private/special attributes.

ConorMacBride commented 3 years ago

Just rebased this. Failures are due to past sphinx versions not having docutils<0.18 specified: https://github.com/sphinx-doc/sphinx/issues/9777. This also causes issues for the RTD build which by default installs older sphinx<2.

og113 commented 1 year ago

I see that this pull request is fairly old but just wanted to say that I'd really appreciate this functionality.

bsipocz commented 1 year ago

@ConorMacBride - would you mind rebasing the PR to check on how far it's from getting ready for review?

ConorMacBride commented 1 year ago

I rebased and added a commit to remove PyPI codecov, but that should be a separate PR. I don't like how these new options are configured. I think it would be better if the classes were set within the directives in the rst files, and not listed in conf.py. I couldn't find a way to do that when I opened this PR. Also, it might be good to be able to apply these options to a whole module or the whole package, but currently I think it will only take a list of classes.

bsipocz commented 1 year ago

Would you mind to open that separate PR for codecov, or shall I? I don't expect anything else failing on main, but cron is rather infrequent, so who knows.

ConorMacBride commented 1 year ago

I've opened #163 to remove codecov. py310-test-sphinxdev is failing there also.

bsipocz commented 1 year ago

I had a quick look in the other open PRs, and wonder how this would be another approach for this same problem? https://github.com/astropy/sphinx-automodapi/pull/103

ConorMacBride commented 1 year ago

103 would have worked for my use case, although I think my need to document private methods was due to bad API design! I think #103 is more useful and should be merged instead. @og113, would that also work for you? (specifying a global list of method names to include that begin with `_`)

og113 commented 1 year ago

A global list of method names that begin with an underscore to document would work for me, yes. But, does #103 explicitly exclude the possibility of documenting __init__ or __call__? If so, can __init__ and __call__ be documented with a separate option/method?

pllim commented 1 year ago

@bsipocz , does #165 also supersede this? Thanks!

bsipocz commented 1 year ago

yes, if Conor and og113 are happy with that as an alternative, we could close this one at merge time.

astropy / sphinx-automodapi

Options to document private/special methods #121

103 would have worked for my use case, although I think my need to document private methods was due to bad API design! I think #103 is more useful and should be merged instead. @og113, would that also work for you? (specifying a global list of method names to include that begin with `_`)

astropy / sphinx-automodapi

Options to document private/special methods #121

103 would have worked for my use case, although I think my need to document private methods was due to bad API design! I think #103 is more useful and should be merged instead. @og113, would that also work for you? (specifying a global list of method names to include that begin with _)

103 would have worked for my use case, although I think my need to document private methods was due to bad API design! I think #103 is more useful and should be merged instead. @og113, would that also work for you? (specifying a global list of method names to include that begin with `_`)