fix: make Black, Flake8, Sphinx play nice together by tweaking a few …

…Flake8 settings (#479)

.flake8

@@ -1,19 +1,52 @@
-# Unfortunately, flake8 does not support pyproject.toml configuration.
+# Unfortunately, Flake8 does not support pyproject.toml configuration.
 # https://github.com/PyCQA/flake8/issues/234
 #
-# Disabling the following noise:
-# D105: Missing docstring in magic method
-# E501: line too long, managed better by Bugbear's B950
+# More details regarding Flake8 and Black interplay:
+# https://github.com/psf/black/blob/main/docs/guides/using_black_with_other_tools.md#flake8
 [flake8]
-ignore = D105, E501
+
+# Enable a few additional checks.
+#
+# https://github.com/PyCQA/flake8-bugbear#how-to-enable-opinionated-warnings
+# B9: Bugbear's extended opinionated checks
+#
+# https://pycodestyle.pycqa.org/en/latest/intro.html#error-codes
+# W504: line break after binary operator (Black compliant)
+extend-select = B9, W504
+
+# Disable several warnings that don't play nice with PEP8 or Black,
+# or that are a bit of a nuisance in general.
+#
+# http://www.pydocstyle.org/en/latest/error_codes.html
+# D105: Missing docstring in magic method
+#
+# https://pycodestyle.pycqa.org/en/latest/intro.html#error-codes
+# E203: whitespace before ‘,’, ‘;’, or ‘:’ (not Black compliant)
+# E501: line too long (managed better by Bugbear's B950)
+# W503: line break before binary operator (not Black compliant)
+#
+# https://github.com/peterjc/flake8-rst-docstrings#configuration
+# RST307: Error in "XXX" directive
+ignore = D105, E203, E501, RST307, W503
 per-file-ignores =
+
+# More assorted goodness.
 max-line-length = 120
 show-source = true
 
-# Enable Bugbear's extended opinionated checks.
-# https://github.com/PyCQA/flake8-bugbear#how-to-enable-opinionated-warnings
-extend-select = B9
-
-# Ensure that flake8 warnings are silenced correctly.
+# Ensure that Flake8 warnings are silenced correctly:
 # https://github.com/plinss/flake8-noqa#options
 noqa-require-code = true
+
+# Ensure that Sphinx extensions of .rst are recognized:
+# https://github.com/peterjc/flake8-rst-docstrings#configuration
+rst-roles = class, func, ref
+rst-directives = envvar, exception
+rst-substitutions = version
+
+# Ensure that Sphinx docstrings use Numpy format for docstrings:
+# https://github.com/PyCQA/flake8-docstrings
+#
+# For details on the Numpy format:
+# https://www.sphinx-doc.org/en/master/usage/extensions/example_numpy.html
+docstring-convention = numpy