Draft: Add sphinx documentation

The mechanism for building docs was copied from EveryBeam; it parses both Doxygen documentation and python documentation into a sphinx page.

python/docstrings_polarization.h

+/*
+  This file contains docstrings for use in the Python bindings.
+  Do not edit! They were automatically extracted by pybind11_mkdoc.
+ */
+
+#define __EXPAND(x) x
+#define __COUNT(_1, _2, _3, _4, _5, _6, _7, COUNT, ...) COUNT
+#define __VA_SIZE(...) __EXPAND(__COUNT(__VA_ARGS__, 7, 6, 5, 4, 3, 2, 1))
+#define __CAT1(a, b) a##b
+#define __CAT2(a, b) __CAT1(a, b)
+#define __DOC1(n1) __doc_##n1
+#define __DOC2(n1, n2) __doc_##n1##_##n2
+#define __DOC3(n1, n2, n3) __doc_##n1##_##n2##_##n3
+#define __DOC4(n1, n2, n3, n4) __doc_##n1##_##n2##_##n3##_##n4
+#define __DOC5(n1, n2, n3, n4, n5) __doc_##n1##_##n2##_##n3##_##n4##_##n5
+#define __DOC6(n1, n2, n3, n4, n5, n6) \
+  __doc_##n1##_##n2##_##n3##_##n4##_##n5##_##n6
+#define __DOC7(n1, n2, n3, n4, n5, n6, n7) \
+  __doc_##n1##_##n2##_##n3##_##n4##_##n5##_##n6##_##n7
+#define DOC(...) \
+  __EXPAND(__EXPAND(__CAT2(__DOC, __VA_SIZE(__VA_ARGS__)))(__VA_ARGS__))
+
+#if defined(__GNUG__)
+#pragma GCC diagnostic push
+#pragma GCC diagnostic ignored "-Wunused-variable"
+#endif
+
+static const char* __doc_aocommon_Polarization =
+    R"doc(Class for various simple polarization related values.
+
+The visibility relations for converting polarizations are:
+
+RR = I + V ; I = (RR + LL)/2 RL = Q + iU ; Q = (RL + LR)/2 LR = Q - iU
+; U = -i (RL - LR)/2 LL = I - V ; V = (RR - LL)/2
+
+XX = I + Q ; I = (XX + YY)/2 XY = U + iV ; Q = (XX - YY)/2 YX = U - iV
+; U = (XY + YX)/2 YY = I - Q ; V = -i(XY - YX)/2
+
+These definitions assume that 'X' and 'Y' are labelled as they are in
+CASA measurement sets: X is North-South.
+
+Note that uv-fits files have the polarizations labelled such that X is
+East-West, confusingly. We have also observed that at present (2016)
+CASA's importuvfits does not swap the polarizations, hence Measurement
+Sets exist that have the polarizations labelled wrong. The IEEE
+definition is to have X be N-S. See also:
+http://adsabs.harvard.edu/abs/1996A%26AS..117..161H)doc";
+
+static const char* __doc_aocommon_Polarization_AipsIndexToEnum = R"doc()doc";
+
+static const char* __doc_aocommon_Polarization_CircularToStokes = R"doc()doc";
+
+static const char* __doc_aocommon_Polarization_EnumToAipsIndex = R"doc()doc";
+
+static const char* __doc_aocommon_Polarization_GetVisibilityCount =
+    R"doc(Get the number of visibilities that are required to store this
+polarization. For the special polarization values Instrument and
+DiagonalInstrument, 4 and 2 are returned respectively. For other
+polarizations, the value 1 is returned.)doc";
+
+static const char* __doc_aocommon_Polarization_HasDualLinearPolarization =
+    R"doc()doc";
+
+static const char* __doc_aocommon_Polarization_HasDualPolarization =
+    R"doc()doc";
+
+static const char* __doc_aocommon_Polarization_HasFullCircularPolarization =
+    R"doc()doc";
+
+static const char* __doc_aocommon_Polarization_HasFullLinearPolarization =
+    R"doc()doc";
+
+static const char* __doc_aocommon_Polarization_HasFullPolarization =
+    R"doc()doc";
+
+static const char* __doc_aocommon_Polarization_HasFullStokesPolarization =
+    R"doc()doc";
+
+static const char* __doc_aocommon_Polarization_IndexToStokes = R"doc()doc";
+
+static const char* __doc_aocommon_Polarization_IsComplex = R"doc()doc";
+
+static const char* __doc_aocommon_Polarization_IsStokes = R"doc()doc";
+
+static const char* __doc_aocommon_Polarization_LinearToStokes = R"doc()doc";
+
+static const char* __doc_aocommon_Polarization_ParseList = R"doc()doc";
+
+static const char* __doc_aocommon_Polarization_ParseString = R"doc()doc";
+
+static const char* __doc_aocommon_Polarization_PolarizationEnum = R"doc()doc";
+
+static const char*
+    __doc_aocommon_Polarization_PolarizationEnum_DiagonalInstrumental =
+        R"doc(DiagonalInstrumental is similar to Instrumental, but refers to
+situations where only the diagonal instrumental values are of concern.
+It can for example refer to XX and YY; or LL and RR. For WSClean, this
+value is used when imaging Stokes I with diagonal a-term corrections,
+such that only the XX and YY visibilities are required.)doc";
+
+static const char* __doc_aocommon_Polarization_PolarizationEnum_FullStokes =
+    R"doc(FullStokes is a special value representing that all four Stokes
+polarizations (I, Q, U, V) are stored.)doc";
+
+static const char* __doc_aocommon_Polarization_PolarizationEnum_Instrumental =
+    R"doc(Instrumental is a special value representing that four polarizations
+are stored, and these are the 'raw' measurement set polarizations,
+e.g. XX, XY, YX, YY. It is used as a special value that e.g. can be
+passed to a WSClean's MSProvider, which would mean all values are
+gridded at once, as required for an a-term correcting gridder.)doc";
+
+static const char* __doc_aocommon_Polarization_PolarizationEnum_LL =
+    R"doc()doc";
+
+static const char* __doc_aocommon_Polarization_PolarizationEnum_LR =
+    R"doc()doc";
+
+static const char* __doc_aocommon_Polarization_PolarizationEnum_RL =
+    R"doc()doc";
+
+static const char* __doc_aocommon_Polarization_PolarizationEnum_RR =
+    R"doc()doc";
+
+static const char* __doc_aocommon_Polarization_PolarizationEnum_StokesI =
+    R"doc()doc";
+
+static const char* __doc_aocommon_Polarization_PolarizationEnum_StokesQ =
+    R"doc()doc";
+
+static const char* __doc_aocommon_Polarization_PolarizationEnum_StokesU =
+    R"doc()doc";
+
+static const char* __doc_aocommon_Polarization_PolarizationEnum_StokesV =
+    R"doc()doc";
+
+static const char* __doc_aocommon_Polarization_PolarizationEnum_XX =
+    R"doc()doc";
+
+static const char* __doc_aocommon_Polarization_PolarizationEnum_XY =
+    R"doc()doc";
+
+static const char* __doc_aocommon_Polarization_PolarizationEnum_YX =
+    R"doc()doc";
+
+static const char* __doc_aocommon_Polarization_PolarizationEnum_YY =
+    R"doc()doc";
+
+static const char* __doc_aocommon_Polarization_StokesToIndex = R"doc()doc";
+
+static const char* __doc_aocommon_Polarization_StokesToLinear = R"doc()doc";
+
+static const char* __doc_aocommon_Polarization_TypeTo4PolIndex = R"doc()doc";
+
+static const char* __doc_aocommon_Polarization_TypeToFullString = R"doc()doc";
+
+static const char* __doc_aocommon_Polarization_TypeToIndex = R"doc()doc";
+
+static const char* __doc_aocommon_Polarization_TypeToIndex_2 = R"doc()doc";
+
+static const char* __doc_aocommon_Polarization_TypeToIndex_3 = R"doc()doc";
+
+static const char* __doc_aocommon_Polarization_TypeToShortString = R"doc()doc";
+
+#if defined(__GNUG__)
+#pragma GCC diagnostic pop
+#endif