python-can icon indicating copy to clipboard operation
python-can copied to clipboard
verified publisher icon hardbyte

Fixing Sphinx - Documentation improvements

Open felixdivo opened this issue 7 years ago • 8 comments

Running sphinx-build doc/ doc/_build -n reveals many apparent problems. Do we need to solve them?

felixdivo avatar Feb 22 '18 19:02 felixdivo

Yes as it probably effects how the docs are rendered. I'll take a look.

hardbyte avatar Feb 23 '18 22:02 hardbyte

Maybe we should test this on the CI server?

felixdivo avatar Mar 16 '18 17:03 felixdivo

Update on this: The docs are now built as part of the Python 3.6 test on Travis CI with the option -n to reveal any problems. They are not considered errors for now. Any help is appreciated.

felixdivo avatar Aug 06 '18 17:08 felixdivo

Here are the errors in master from the 3.1 merge:

/home/travis/build/hardbyte/python-can/can/interface.py:docstring of can.Bus:1: WARNING: py:class reference target not found: can.bus.BusABC
/home/travis/build/hardbyte/python-can/can/bus.py:docstring of can.BusABC.send_periodic:9: WARNING: py:meth reference target not found: CyclicTask.stop
/home/travis/build/hardbyte/python-can/can/bus.py:docstring of can.BusABC.send_periodic:22: WARNING: py:meth reference target not found: stop
/home/travis/build/hardbyte/python-can/can/bus.py:docstring of can.BusABC.state:: WARNING: py:class reference target not found: NamedTuple
/home/travis/build/hardbyte/python-can/can/thread_safe_bus.py:docstring of can.ThreadSafeBus:1: WARNING: py:class reference target not found: ObjectProxy
/home/travis/build/hardbyte/python-can/can/thread_safe_bus.py:docstring of can.ThreadSafeBus:10: WARNING: py:meth reference target not found: can.BusABC._recv_internal
/home/travis/build/hardbyte/python-can/can/thread_safe_bus.py:docstring of can.ThreadSafeBus:10: WARNING: py:meth reference target not found: can.BusABC._recv_internal
/home/travis/build/hardbyte/python-can/can/interfaces/canalystii.py:docstring of can.interfaces.canalystii.CANalystIIBus:1: WARNING: py:class reference target not found: can.bus.BusABC
/home/travis/build/hardbyte/python-can/can/interfaces/iscan.py:docstring of can.interfaces.iscan.IscanBus:1: WARNING: py:class reference target not found: can.bus.BusABC
/home/travis/build/hardbyte/python-can/doc/interfaces/ixxat.rst:11: WARNING: py:meth reference target not found: can.interfaces.ixxat.canlib.IXXATBus.send_periodic
/home/travis/build/hardbyte/python-can/can/interfaces/kvaser/canlib.py:docstring of can.interfaces.kvaser.canlib.KvaserBus:1: WARNING: py:class reference target not found: can.bus.BusABC
/home/travis/build/hardbyte/python-can/can/interfaces/kvaser/canlib.py:docstring of can.interfaces.kvaser.canlib.KvaserBus.get_stats:: WARNING: py:class reference target not found: can.interfaces.kvaser.structures.BusStatistics
/home/travis/build/hardbyte/python-can/can/interfaces/ics_neovi/neovi_bus.py:docstring of can.interfaces.ics_neovi.NeoViBus:1: WARNING: py:class reference target not found: can.bus.BusABC
/home/travis/build/hardbyte/python-can/can/interfaces/nican.py:docstring of can.interfaces.nican.NicanBus:1: WARNING: py:class reference target not found: can.bus.BusABC
/home/travis/build/hardbyte/python-can/can/interfaces/nican.py:docstring of can.interfaces.nican.NicanBus:5: WARNING: py:meth reference target not found: can.interfaces.nican.NicanBus.__init__
/home/travis/build/hardbyte/python-can/can/interfaces/pcan/pcan.py:docstring of can.interfaces.pcan.PcanBus:1: WARNING: py:class reference target not found: can.bus.BusABC
/home/travis/build/hardbyte/python-can/can/interfaces/pcan/pcan.py:docstring of can.interfaces.pcan.PcanBus:3: WARNING: py:meth reference target not found: can.interface.pcan.PcanBus.flash
/home/travis/build/hardbyte/python-can/can/interfaces/pcan/pcan.py:docstring of can.interfaces.pcan.PcanBus:3: WARNING: py:meth reference target not found: can.interface.pcan.PcanBus.status
/home/travis/build/hardbyte/python-can/can/interfaces/pcan/pcan.py:docstring of can.interfaces.pcan.PcanBus:: WARNING: py:class reference target not found: can.bus.BusState
/home/travis/build/hardbyte/python-can/can/interfaces/pcan/pcan.py:docstring of can.interfaces.pcan.PcanBus.state:: WARNING: py:class reference target not found: NamedTuple
/home/travis/build/hardbyte/python-can/can/interfaces/serial/serial_can.py:docstring of can.interfaces.serial.serial_can.SerialBus:1: WARNING: py:class reference target not found: can.bus.BusABC
/home/travis/build/hardbyte/python-can/can/interfaces/serial/serial_can.py:docstring of can.interfaces.serial.serial_can.SerialBus:3: WARNING: py:meth reference target not found: can.interfaces.serial.SerialBus._recv_internal
/home/travis/build/hardbyte/python-can/can/interfaces/slcan.py:docstring of can.interfaces.slcan.slcanBus:1: WARNING: py:class reference target not found: can.bus.BusABC
/home/travis/build/hardbyte/python-can/can/interfaces/socketcan/socketcan.py:docstring of can.interfaces.socketcan.CyclicSendTask:1: WARNING: py:class reference target not found: can.broadcastmanager.ModifiableCyclicTaskABC
/home/travis/build/hardbyte/python-can/can/interfaces/socketcan/socketcan.py:docstring of can.interfaces.socketcan.CyclicSendTask:1: WARNING: py:class reference target not found: can.broadcastmanager.RestartableCyclicTaskABC
/home/travis/build/hardbyte/python-can/can/interfaces/socketcan/socketcan.py:docstring of can.interfaces.socketcan.SocketcanBus:1: WARNING: py:class reference target not found: can.bus.BusABC
/home/travis/build/hardbyte/python-can/can/interfaces/socketcan/socketcan.py:docstring of can.interfaces.socketcan.SocketcanBus:1: WARNING: py:meth reference target not found: can.BusABC._detect_available_configs
/home/travis/build/hardbyte/python-can/can/interfaces/systec/ucanbus.py:docstring of can.interfaces.systec.ucanbus.UcanBus:1: WARNING: py:class reference target not found: can.bus.BusABC
/home/travis/build/hardbyte/python-can/can/interfaces/systec/ucanbus.py:docstring of can.interfaces.systec.ucanbus.UcanBus:: WARNING: py:class reference target not found: can.bus.BusState
/home/travis/build/hardbyte/python-can/can/interfaces/systec/ucanbus.py:docstring of can.interfaces.systec.ucanbus.UcanBus.state:: WARNING: py:class reference target not found: NamedTuple
/home/travis/build/hardbyte/python-can/doc/interfaces/systec.rst:74: WARNING: py:class reference target not found: can.broadcastmanager.ThreadBasedCyclicSendTask
/home/travis/build/hardbyte/python-can/can/interfaces/usb2can/usb2canInterface.py:docstring of can.interfaces.usb2can.Usb2canBus:1: WARNING: py:class reference target not found: can.bus.BusABC
/home/travis/build/hardbyte/python-can/can/interfaces/vector/canlib.py:docstring of can.interfaces.vector.VectorBus:1: WARNING: py:class reference target not found: can.bus.BusABC
/home/travis/build/hardbyte/python-can/doc/internal-api.rst:16: WARNING: py:meth reference target not found: can.BusABC._recv_internal
/home/travis/build/hardbyte/python-can/doc/internal-api.rst:26: WARNING: py:meth reference target not found: can.BusABC._send_periodic_internal
/home/travis/build/hardbyte/python-can/doc/internal-api.rst:28: WARNING: py:meth reference target not found: can.BusABC._apply_filters
/home/travis/build/hardbyte/python-can/doc/internal-api.rst:30: WARNING: py:meth reference target not found: can.BusABC._detect_available_configs
/home/travis/build/hardbyte/python-can/doc/internal-api.rst:38: WARNING: py:meth reference target not found: can.BusABC._recv_internal
/home/travis/build/hardbyte/python-can/doc/internal-api.rst:41: WARNING: py:meth reference target not found: can.BusABC._recv_internal
/home/travis/build/hardbyte/python-can/can/bus.py:docstring of can.BusABC._apply_filters:: WARNING: py:class reference target not found: Iterator
/home/travis/build/hardbyte/python-can/can/bus.py:docstring of can.BusABC._detect_available_configs:: WARNING: py:class reference target not found: Iterator
/home/travis/build/hardbyte/python-can/can/bus.py:docstring of can.BusABC._send_periodic_internal:13: WARNING: py:meth reference target not found: stop
/home/travis/build/hardbyte/python-can/can/bus.py:docstring of can.BusABC.send_periodic:9: WARNING: py:meth reference target not found: CyclicTask.stop
/home/travis/build/hardbyte/python-can/can/bus.py:docstring of can.BusABC.send_periodic:22: WARNING: py:meth reference target not found: stop
/home/travis/build/hardbyte/python-can/can/bus.py:docstring of can.BusABC.state:: WARNING: py:class reference target not found: NamedTuple
/home/travis/build/hardbyte/python-can/can/listener.py:docstring of can.BufferedReader:1: WARNING: py:class reference target not found: can.listener.Listener
/home/travis/build/hardbyte/python-can/can/listener.py:docstring of can.AsyncBufferedReader:1: WARNING: py:class reference target not found: can.listener.Listener
/home/travis/build/hardbyte/python-can/can/io/logger.py:docstring of can.Logger:1: WARNING: py:class reference target not found: can.listener.Listener
/home/travis/build/hardbyte/python-can/can/io/printer.py:docstring of can.Printer:1: WARNING: py:class reference target not found: can.listener.Listener
/home/travis/build/hardbyte/python-can/can/io/csv.py:docstring of can.CSVWriter:1: WARNING: py:class reference target not found: can.listener.Listener
/home/travis/build/hardbyte/python-can/can/io/sqlite.py:docstring of can.SqliteWriter:1: WARNING: py:class reference target not found: can.listener.BufferedReader
/home/travis/build/hardbyte/python-can/can/io/sqlite.py:docstring of can.SqliteReader:6: WARNING: py:func reference target not found: builtin.len
/home/travis/build/hardbyte/python-can/can/io/sqlite.py:docstring of can.SqliteReader.read_all:: WARNING: py:class reference target not found: Generator
/home/travis/build/hardbyte/python-can/can/io/asc.py:docstring of can.ASCWriter:1: WARNING: py:class reference target not found: can.listener.Listener
/home/travis/build/hardbyte/python-can/can/io/canutils.py:docstring of can.CanutilsLogWriter:1: WARNING: py:class reference target not found: can.listener.Listener
/home/travis/build/hardbyte/python-can/can/io/blf.py:docstring of can.BLFWriter:1: WARNING: py:class reference target not found: can.listener.Listener

hardbyte avatar Feb 23 '19 10:02 hardbyte

Replacing .. autoclass:: can.Listener with .. autoclass:: can.listener.Listener in listeners.rst solves many WARNING: py:class reference target not found: can.listener.Listener warnings. But it obviously shows the class as class can.listener.Listener:, which is not what we want. How can we solve this?

felixdivo avatar Feb 24 '19 12:02 felixdivo

I was able to solve

[...]/python-can/can/interfaces/pcan/pcan.py:docstring of can.interfaces.pcan.PcanBus.state:: WARNING: py:class reference target not found: collections.namedtuple

and opened an issue in the sphinx repo since it seems to be a problem in the docs. sphinx-doc/sphinx#6100

felixdivo avatar Feb 24 '19 12:02 felixdivo

Replacing .. autoclass:: can.Listener with .. autoclass:: can.listener.Listener in listeners.rst solves many WARNING: py:class reference target not found: can.listener.Listener warnings. But it obviously shows the class as class can.listener.Listener:, which is not what we want. How can we solve this?

This is also a problem with BusABC and the can.broadcastmanager.* module. If we can fix this, we should be able to shrink the number of issues by a lot. I could not find any helpful advice yet ...

felixdivo avatar Feb 26 '19 19:02 felixdivo

Maybe these could help (added in Sphinx Release 4.0.0 beta1 (released Apr 12, 2021)):

  • https://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html#directive-option-py-function-canonical
  • (https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-python_use_unqualified_type_names)

felixdivo avatar Apr 14 '21 12:04 felixdivo

@zariiii9003 Is this still relevant?

felixdivo avatar Nov 16 '22 08:11 felixdivo

I think we can close it, we've made significant progress improving the docs and reducing the warnings

hardbyte avatar Nov 24 '22 20:11 hardbyte