bluesky / ophyd

hardware abstraction in Python with an emphasis on EPICS
https://blueskyproject.io/ophyd
BSD 3-Clause "New" or "Revised" License
51 stars 79 forks source link

reST formatting errors in PseudoPositioner #1191

Closed prjemian closed 5 months ago

prjemian commented 6 months ago

When building Sphinx docs for a new package including the ophyd PseudoPositioner, Sphinx raises this exception:

path/to/project/file.py:docstring of ophyd.pseudopos.PseudoPositioner._get_real_positioners:3: WARNING: Inline interpreted text or phrase reference start-string without end-string.
prjemian commented 6 months ago

In this line: https://github.com/bluesky/ophyd/blob/5c03c3fff974dc6390836fc83dae4c247a35e662/ophyd/pseudopos.py#L548

the intent is to show Positioner and PseudoSingle as computer code. The correct reST syntax is to use two back-ticks when enclosing such text. The root cause of the problem, though, is rendering the term "PseudoSingles". This cannot be rendered in reST (maybe it could be but it is not an easy task).

Local editing shows that this rewrite will not raise the error:

        All ``Positioner`` components which are not ``PseudoSingle`` objects will be