Options to document private/special methods

[ConorMacBride]

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]

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

[og113]

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

[bsipocz]

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

[ConorMacBride]

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]

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]

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

[bsipocz]

I had a quick look in the other open PRs, and wonder how this would be another approach for this same problem? #103

[ConorMacBride]

#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]

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]

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

[bsipocz]

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