Make documentation work for @multimethod functions

[Joschua-Conrad]

The Sphinx-generated documentation includes using autodoc on functions/methods, which are overloaded through multimethod. For methods (such as Location.__init__), that works just fine. The feature is enabled through doc/ext/sphinx_autodoc_multimethod.py.

However, for multimethod functions defined at the toplevel of a module, the documentation is broken:

• edgeOn appears strange (docstring/prototype of overloaded function is just placed as-is) and raises an Inline emphasis start-string without end-string warning in build_docs.sh. The asterix marking a list of arguments in a secondary definition is interpreted wrong.
• loft has exactly the same issues.
• wire I guess only works, because the overloaded function has no docstring.
• face appears strange with docstring/prototype of overloaded function placed as-is, but raises no Sphinx warning.
• These functions have the same issue like face
  • shell
  • solid
  • compound
  • vertex
  • spline
  • plane
  • cone
  • text
  • sweep

I guess doc/ext/sphinx_autodoc_multimethod.py needs fixing. But to be honest, I don't understand in-detail how this Sphinx extension works, and my attempts to fix it failed. The extension was created and edited by @lorenzncode. I browsed through past PRs and issues related to the history of the Sphinx extension, but none refers explicitly to module-level functions.

[lorenzncode]

@Joschua-Conrad Thanks for checking this!

When the Sphinx extension was first added, these functions did not yet exist.

I agree the extension likely needs fixing to handle the new functions. In the meantime the extension could be disabled until it is fixed.

[Joschua-Conrad]

The extension can be disabled by removing this line. But that also ruins the docs of all the methods, where the extension currently does its job very nicely. And I guess most users who use CadQuery right now rely on Workplane, Sketch, and their methods (e.g. Sketch.moved), such that most users won't even notice any problems.

So I'd keep the extension enabled and just live with the minor problems in the meantime 😄