Group members in API docs

Author: cburgdorf

docs/_static/css/custom.css

@@ -18,3 +18,46 @@ tt, code, pre {
   margin: 0;
   padding: 0;
 }
+
+/* We instruct sphinx to order members groupwise and use the following css to add headlines.
+Notice that while the css differentiates between methods, classmethods and staticmethods,
+unfortunately, sphinx groups these all alphabetically as methods which means we only
+display them as one "methods" group. */
+
+dl.attribute:before {
+  content: "Attributes";
+}
+
+dl.method:before,
+dl.classmethod:before,
+dl.staticmethod:before {
+  content: "Methods";
+}
+
+dl.method:before,
+dl.attribute:before,
+dl.classmethod:before,
+dl.staticmethod:before {
+  background: #e7f2fa;
+  border-top: solid 3px #6ab0de;
+  color: #000;
+  display: inline-block;
+  font-weight: bold;
+  margin: 5px 0 10px 0;
+  padding: 5px;
+}
+
+/* Remove method header if a previous element already introduced it */
+dl.attribute + dl.attribute:before,
+/* We have to treat all these as just "methods" (see comment further above) */
+dl.method + dl.method:before,
+dl.classmethod + dl.method:before,
+dl.staticmethod + dl.method:before,
+dl.method + dl.classmethod:before,
+dl.classmethod + dl.classmethod:before,
+dl.staticmethod + dl.classmethod:before,
+dl.method + dl.staticmethod:before,
+dl.staticmethod + dl.staticmethod:before,
+dl.classmethod + dl.staticmethod:before {
+  display: none;
+}

docs/conf.py

@@ -50,6 +50,8 @@
     'undoc-members': None,
 }
 
+autodoc_member_order = 'groupwise'
+autodoc_mock_imports = ["snappy"]
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']

newsfragments/1797.doc.rst

@@ -1 +1,3 @@
-Tweak layout of API docs to improve readability
+Tweak layout of API docs to improve readability
+
+Group API docs by member (methods, attributes)

newsfragments/794.doc.rst

@@ -0,0 +1,3 @@
+In the API docs display class methods, static methods and methods as one group "methods".
+While we ideally wish to separate these, Sphinx keeps them all as one group which we'll
+be following until we find a better option.