Duplicate docstrings between related classes and functions

[vyasr]

Feature description

#235 follows a recurring theme where lack of duplication in the documentation leads to confusion because it's not always clear to users how the documentation of different classes/functions is linked or why. We should explore better ways to share docstrings without actually duplicating (which would increase maintenance costs and the chance of erroneous docstrings if we miss updating one of many places where something is copy-pasted).

Proposed solution

The most obvious solution is to perform runtime inspection and modification of docstrings by modifying the __doc__ attribute. In case such runtime modification runs into any issues with Sphinx documentation generation, we could instead use a more kludgy but perhaps less fragile solution like direct inclusion using reST's include directive.

Additional context

As long as we are not maintaining the same code/documentation in multiple places, I think duplication in the user-facing documentation is desirable. @atravitz has also indicated that such duplication would alleviate some of her confusion.

[bdice]

1. __doc__ modification works fine with Sphinx.
2. Using the include directive would make docstrings useless on the command line. I use help() frequently and would prefer not to rely on rST directives.

[mikemhenry]

@atravitz you have been doing some excellent doc work lately, is this still an issue? I can't remember if made a decision on this.

[mikemhenry]

We should also have this resolved by 2.x (if not sooner)

[stale]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.

[vyasr]

I think we still want to target this change for 2.0 if possible since docs are quite valuable for us. @atravitz do you know if there was more to be done here?

[vyasr]

@atravitz could you provide an update here?

[vyasr]

I'm going to close this issue. Our docs have improved tremendously since it was first opened. There are probably still cases where we could benefit from more duplication of documentation, but we can address those on a more case-by-case basis when they arise.