some api documentation generation improvements

[RobinD42]

From Ardavan:

I noticed a few minor improvements we can make to the generate_py_api.py
which required me to manually edit Python_User_Interface.md:

• in the entry for "EigenModeSource" and "GaussianBeamSource" in
  meep/python/source.py, the line "component=mp.ALL_COMPONENTS" is being
  replaced with "component=20" (it would be good to preserve the original
  "mp.ALL_COMPONENTS"). Same for "direction=mp.AUTOMATIC" and
  "eig_kpoint=mp.Vector3()"

• in the init code block of the PML object, the line
  "pml_profile=lambda u: u * u)" in meep/python/simulation.py is showing
  up as "pml_profile=<function PML. at 0x7f4f93f958c8>)" (it would
  be good to preserve the text showing the inline function definition)

• in some cases (i.e., "add_mode_monitor(self, *args, **kwargs):"),
  an unnecessary blank space is inserted after the colon

• the line "See help(type(self)) for accurate signature." was
  changed to "See help(type(self)) for accurate signature." (i.e.,
  backticks were necessary to place the text inside a code block but I
  couldn't find where this line actually appears in either
  meep/python/*.py, Python_User_Interface.md.in, or generate_py_api.py)

[RobinD42]

Also:

Do we need to document the new Verbosity class that you added in #1302 ("Add verbosity flag for MPB")? Should the "verbosity" parameter documented in https://meep.readthedocs.io/en/latest/Python_User_Interface/#miscellaneous-functions-reference be updated/replaced?

[RobinD42]

@oskooi,

the line "See help(type(self)) for accurate signature." ... but I couldn't find where this line actually appears...

That text comes from the docstring for object.__init__. When a class has an __init__ without a docstring then the introspection module will look for a docstring up the inheritance hierarchy that it can use instead. So the best way to deal with this is to ensure that the __init__ for all documented classes have a docstring.

In [1]: object.__init__.__doc__
Out[1]: 'Initialize self.  See help(type(self)) for accurate signature.'