Notes on Sphinx and reStructuredText

Sphinx is the programme that creates the various html files, java, and other files that together constitute the website.

reStructuredText (reST) is the markup language that is used to provide Sphinx with the guide for what to produce.

(This page is based on the introduction Restructured Text file that is provided with the better of the two tutorials that I have found, this one coming from the ‘Read the Docs’ community and can be found at this link RtD_Sphinx_Tutorial. By the way, that is an example of the format to use to include a URL! I mention the source because lower down I’ve left some of the original in place, just in case it might prove to be a useful ‘how to do it’ example!)

Overview of Sphinx

Sphinx needs a configuration file (written in python) and at least one ReST file

Overview of ReST

Directives will be of the format .. Directive:: and are keywords in ReST that alert Sphinx to do something different. Clicking on this link will take you to a primer on reStructuredText.

There is a Stack_Overview-reST article that is quite good.

Things to note

When setting up the ART-python project from within Documents/36-Sphinx everything seemed to work well with the conf.py file set up to point at Documents/25-Python/site-packages for the source modules. But trying to do the same thing for Meter_Readings didn’t work! I ended up using the sphinx-apidoc command as documented here. The command that worked was:

sphinx-apidoc -o ./source ../../25-Python/Meter_Readings

Todo

Work out how code-block works - it seems it needs a single parameter which I guess is a pointer to the block of code to be displayed.

Error in "code-block" directive:
1 argument(s) required, 0 supplied.
.. code-block::
sphinx-apidoc -o ./source ../../25-Python/Meter_Readings``

Todo

include the default reST annotations for a function

"""[Summary]

:param [ParamName]: [ParamDescription], defaults to [DefaultParamVal]
:type [ParamName]: [ParamType](, optional)
...
:raises [ErrorType]: [ErrorDescription]
...
:return: [ReturnDescription]
:rtype: [ReturnType]"""

ReText

A useful reST editor. Some rough edges, but written in python so presumably I can edit it!

Using configuration file: /home/andrew/.config/ReText project/ReText.conf

ReText-wiki

Stuff from the original page

• kept to show some other ‘directives’ like

simpleble.SimpleBleClient has been designed and implemented with this use-case in mind. As such, if you are looking for a package to allow you to connect to multiple devices, then know that off-the-self this package DOES NOT allow you to do so. However, implementing such a feature is an easily achievable task, which has been planned for sometime in the near future and if there proves to be interest on the project, I would be happy to speed up the process.

• and

bluepy.btle.Peripheral classes have been brought forward to the simpleble.SimpleBleClient class, the same has not been done for the bluepy.btle.Descriptor, meaning that the simpleble.SimpleBleClient cannot be used to directly access the Descriptors. This can however be done easily by obtaining a handle of a simpleble.SimpleBleDevice object and calling the superclass bluepy.btle.Peripheral.getDescriptors() method.