Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

config.types: doc ALL the things! #1719

Merged
merged 1 commit into from
Nov 10, 2019
Merged

config.types: doc ALL the things! #1719

merged 1 commit into from
Nov 10, 2019

Conversation

dgw
Copy link
Member

@dgw dgw commented Oct 22, 2019

There's a lot to parse (ha!) here, but most of it is pretty obvious in purpose. The one thing I think I should explain is why all the parse() and serialize() instances have their own docstrings now.

It's because I was having fun! Just kidding (sort of). It's actually because Sphinx autodoc pulls the docstring from the parent class's method if a subclass's overriding method doesn't have a docstring of its own. In hindsight, writing new docstrings might have been more work than the alternative (setting autodoc_inherit_docstrings = False in docs/conf.py and checking to see if anything broke), but what's done is done at this point. We can still change the setting later.

Also of note: I removed a reference to some feature of StaticSection.configure_setting() that never worked (having prompt be an optional argument). See #864 & ab83a1f.

This set of documentation updates was extracted from the remains of #1689 after development took a different direction for handling # in multi-line ListAttribute config values. I think I removed all the references to stuff that doesn't apply without its former parent commit from that PR… Dear reviewer(s): please double-check to make sure I didn't miss anything else! ❤️

@dgw dgw added this to the 7.0.0 milestone Oct 22, 2019
@dgw dgw requested a review from a team October 22, 2019 23:48
dgw referenced this pull request Oct 22, 2019
You can't get the docstring of an attribute, sadly.

Close #864
Copy link
Contributor

@Exirel Exirel left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Have fun!

sopel/config/types.py Outdated Show resolved Hide resolved
sopel/config/types.py Outdated Show resolved Hide resolved
sopel/config/types.py Outdated Show resolved Hide resolved
sopel/config/types.py Outdated Show resolved Hide resolved
sopel/config/types.py Outdated Show resolved Hide resolved
sopel/config/types.py Outdated Show resolved Hide resolved
sopel/config/types.py Outdated Show resolved Hide resolved
sopel/config/types.py Outdated Show resolved Hide resolved
There's a lot to parse (ha!) here, but most of it is pretty obvious in
purpose. The one thing I think I should explain is why all the `parse()`
and `serialize()` instances have their own docstrings now.

It's because I was having fun! Just kidding (sort of). It's actually
because Sphinx autodoc pulls the docstring from the parent class's
method if a subclass's overriding method doesn't have a docstring of its
own. In hindsight, writing new docstrings might have been *more* work
than the alternative (setting `autodoc_inherit_docstrings = False` in
`docs/conf.py` and checking to see if anything broke), but what's done
is done at this point. We can still change the setting later.

Co-Authored-By: Exirel <florian.strzelecki@gmail.com>
@dgw dgw force-pushed the config.types-docs branch from c916d0e to 4f173c0 Compare October 23, 2019 17:34
@dgw dgw merged commit 58c3e98 into master Nov 10, 2019
@dgw dgw deleted the config.types-docs branch November 10, 2019 12:58
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants