fix docstring issues by adding an explicit handler

[dwreeves]

Long story short: fixes #104.

Locking the dependency uses mkdocstrings's so-called "experimental" handler for docstring parsing. The new one properly parses the docstring in this case whereas the legacy one does not.

[aminalaee]

Nice find ! Do you have any references to this? Because I knew this issue was in mkdocstrings but I couldn't really find this info.

[aminalaee]

Unfortunately this one has some issues too, it adds some attributes automatically to the docs:

[dwreeves]

@aminalaee This is a pretty new tool so I had to do my own digging to find that. I ran mkdocs build locally before and after having the experimental handler (python-mkdocstrings) in my environment

The experimental handler uses another tool under the hood called "griffe" which has a CLI; you can type "griffe sqladmin" to see how it parses the package.

[dwreeves]

I think it's possible to not add those attributes; by default it always includes docstring'd methods, but I think you can override that. I'll check later today.

[aminalaee]

I'll open an issue on mkdocstrings and see how it goes, let's keep this open anyway. I think mkdocstrings is not wrong, we're making form_base_class = Form and it's rendering the form docstrings, but let's see if they have a configuration to avoid this.

[dwreeves]

I do believe the legacy version (default handler) is wrong, and that the experimental version (the handler with mkdocstrings-python==0.6.6 in the requirements) is correct. It may be of use for the mkdocstrings team to be aware of this particular situation and give an option for people control what happens, but I think griffe's current default behavior makes sense to me.

The reason why it's wrong to use wtforms.Form's docstrings is because form_base_class is (1) an alias for another class, and (2) it has its docstring being explicitly overridden by the developer, i.e. the docstring below its definition signals intent from the developer to use a different docstring than wtforms.Form.__doc__.

---

I think the more pressing issue is that the mkdocstrings-python handler does not have a members attribute at the moment. You can see here that the mkdocstrings legacy handler uses the members attribute, but there is no equivalent in the experimental version yet.

[aminalaee]

Well we haven't seen any progress with that issue and both approaches have their problems, I'd say let's comment out form_base_class for now. What do you think?

[dwreeves]

Two options. Both are fine:

1. Comment out in the docs.
2. Have form_base_class's default value be None, and add if self.form_base_class is None: self.form_base_class = Form to the __init__.

[aminalaee]

Thank you for the PR 🎉