add an empty line before a doctest block would help
sphinx to tell where the session starts.

see also https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#doctest-blocks

Signed-off-by: Kefu Chai <tchaikov@gmail.com>
(cherry picked from commit 8685fff)

so it can be rendered by sphinx in a better way.

Signed-off-by: Kefu Chai <tchaikov@gmail.com>
(cherry picked from commit ba3ccee)

breathe calls doxygen for extracting/generating docs from code.
while doxygen complains at seeing undocumented fields/func. these
warnings could fail the sphinx-build command, if it takes warnings
as errors.

in this change, these warnings are silenced.

Signed-off-by: Kefu Chai <tchaikov@gmail.com>
(cherry picked from commit 8891d65)

this helps to silence the warning from sphinx, like

src/pybind/mgr/orchestrator/_interface.py:docstring of orchestrator._interface.Orchestrator.remove_osds:9: WARNING: Field list ends without a blank line; unexpected unindent.

Signed-off-by: Kefu Chai <tchaikov@gmail.com>
(cherry picked from commit d9b8e38)

this allows the "rpc"ized methods of OrchestratorClientMixin to
have the docstring defined by the original methods.

Signed-off-by: Kefu Chai <tchaikov@gmail.com>
(cherry picked from commit d0db2ae)

bump sphinx to latest stable. to address following build failure

ERROR: sphinx-autodoc-typehints 1.17.0 has requirement Sphinx>=4, but you'll have sphinx 3.5.4 which is incompatible.
ERROR: sphinx-substitution-extensions 2022.2.16 has requirement sphinx>=4.0.0, but you'll have sphinx 3.5.4 which is incompatible.

also bump bump sphinx-rtd-theme, otherwise we'd have following
build failure:

ERROR: sphinx-rtd-theme 0.5.2 has requirement docutils<0.17, but you'll have docutils 0.17.1 which is incompatible.

Signed-off-by: Kefu Chai <tchaikov@gmail.com>
(cherry picked from commit 0a5fab5)