to address the issue #894. Most of the fix is just adding a new line…

[AnnieHeroux]

I do not see any of the errors with docstrings when i run make html
It was mostly to add a line between the first line description and the Args line.
Any file with an example for the xml configuration file was an issue, black and sphinx are not playing well. To fix this I use a block but I need everything to have the same indentation .
That being said , It is displaying well in the docs.

@fabcor-maxiv How did you get the nice output in issue #894?

On one hand a block need to have everything with the same indent but just putting a line block for every line keeps the indentation but not as pretty

<device class="BlissActuator">
<username>Detector Cover</username>
<object href="/bliss" role="controller"/>
</device>

<device class="BlissActuator">
    <username>Detector Cover</username>
    <object href="/bliss" role="controller"/>
</device>

On my side, when I run make html , the error are mostly red like below
WARNING: autosummary: failed to import mxcubecore.Command.exporter.MDEvents.

preparing documents... done
copying assets... copying static files... done
copying extra files... done
done
writing output... [100%] dev/autosummary/mxcubecore.HardwareObjects.BlissActuator
generating indices... genindex py-modindex done
highlighting module code... [100%] mxcubecore.utils.dataobject
writing additional pages... search done
dumping search index in English (code: en)... done
dumping object inventory... done
build succeeded, 107 warnings.

[fabcor-maxiv]

@fabcor-maxiv How did you get the nice output in issue #894?

I think when removing the content of the docs/source/dev/autosummary/ directory, and then re-building I get this whole list of docstring issues.

What happens is that Sphinx via its autosummary feature reads the content of the mxcubecore directory and parses all the docstrings to automatically generate all the .rst files in the docs/source/dev/autosummary/ directory, and this is when Sphinx shows all the issues. Afterwards every time a Python file is modified Sphinx re-generates only the associated .rst file in autosummary, instead of all of them.

[fabcor-maxiv]

@AnnieHeroux, I do not seem to be able to reproduce the conflict with black formatting that you mentioned.

I made this change, for example:

diff --git a/mxcubecore/HardwareObjects/BlissActuator.py b/mxcubecore/HardwareObjects/BlissActuator.py
index f2e23c54..56ca17c9 100644
--- a/mxcubecore/HardwareObjects/BlissActuator.py
+++ b/mxcubecore/HardwareObjects/BlissActuator.py
@@ -1,11 +1,12 @@
 """
 Use bliss to set different actuators in/out.
 If private_state not specified, True will be send to set in and False for out.
-Example xml file:
-<device class="BlissActuator">
-  <username>Detector Cover</username>
-  <object href="/bliss" role="controller"/>
-</device>
+Example xml file::
+
+    <device class="BlissActuator">
+      <username>Detector Cover</username>
+      <object href="/bliss" role="controller"/>
+    </device>
 """
 import logging
 from warnings import warn

The generated documentation looks as I expect it and black does not complain.

[beteva]

What works for me and it looks nice when reading the documentation is

"""
Use bliss to set different actuators in/out.
If private_state not specified, True will be send to set in and False for out.

Example xml file:

.. code-block:: xml

 <object class="BlissActuator">
   <username>Detector Cover</username>
   <object href="/bliss" role="controller"/>
   <values>{"IN": True, "OUT": False}</values>
 </object>
"""

Note the blank line above and below the code-block statement as well as the space in front of the first and the last line of the example code!

[marcus-oscarsson]

Hey @AnnieHeroux are you still working on this ?