DiffractedPlanewave objects can only be used with mode decomposition and not mode sources

[oskooi]

Related to #2054.

Some of the (unrelated) changes are from rebuilding the documentation using make python_api_doc.

[stevengj]

Just to be clear, a DiffractedPlanewave specification is perfectly mathematically meaningful for an eigenmode source. However, most of the time you have an incident planewave you will only have a single incident planewave, and it's probably easier to just specify k_point … as long as the plane of incidence is oriented in the xy or xz plane so that you can use the parity feature to select the s or p polarization.

[stevengj]

We don't have a tutorial for using it as a source, which makes it harder to use, but I don't think we should remove it from the manual.

[stevengj]

To launch a planewave at a particular angle, probably the easiest thing to do is to (a) from the angle and frequency, calculate the k_point, and (b) use a DiffractedPlanewave with order 0. (Basically, you are just using it to specify the s and p amplitudes conveniently.)