Add Python docstrings

[RobinD42]

Fixes #1236

First pass implementation of a tool to pull docstrings in markdown format from the Python code, and add them to the main documentation tree.

TODOs:

• Finish copying existing class docs into docstrings
• Prettify the docstrings so they're more readable in the code
• Reorder methods so __init__ always comes first
• Indent class members in the output (perhaps by adding a new CSS style)
• Finish support for top-level function docstrings, add their docstrings
• Add __repr__ methods for classes that are used as default parameter values
• Find way to auto-exclude SWIG and other lower-level or non-public things.
• Handle auto documenting other types of items, such as properties??
• Update intra-doc links to accomodate new document and anchor names
• Remove the current Python Interface doc. (And rename the new one?)

Not part of this PR, but IMO "{Language} User Interface" name is very misleading, "{Language} User API" would be better.

[stevengj]

I like where this is heading!

One possibility would be to emulate the Documenter.jl package for Julia, which inserts Julia docstrings into Markdown documentation. Essentially, we would take our current Python API markdown document, and replace the documentation for e.g. Medium with

```@docs
Medium
```

and then the postprocessing tool would insert the docstring for Medium there.

The advantages of this, rather than generating the Python API docs wholesale, are:

1. We manually decide which things go in the manual, and in what order. No need to filter out SWIG-generated code or undocumented features, for example.

2. We can still surround the docstring code with additional explanations, tutorials, etcetera.

[RobinD42]

Yes, that's a good idea. I was thinking about adding some boolean class-level attribute to indicate if something should be added to the documentation, (defaulting to False if it wasn't present) but using a tag to indicate where to insert the doc is much cleaner, and would also allow to use a non-alphabetic ordering like what is in the original document.

[stevengj]

Is the generated Python_User_Interface.md supposed to be checked in too?

[RobinD42]

I wasn't sure what the preference/policy on that would be. Since it's now generated some projects would just remove it from git. Others would keep it in and developers would need to ensure it is rebuilt and checked in when any changes are made that affect it. What makes the most sense to you?

[stevengj]

It would be nicer to not check it in, and build it automatically on commits. make dist should certainly build it into the tarballs.

Unfortunately, since it requires Meep to be compiled, it may be too complicated for the mkdocs script. One option would be to build it as part of Travis, and store it with Travis build artifacts for later use during documentation generation. That probably requires some digging through the Travis docs to understand the artifacts system.