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 <https://sphinx-rtd-tutorial.readthedocs.io/en/latest/index.html>`_.  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 <https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html>`_ will take you to a primer on reStructuredText.

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

.. _Stack_Overview-rest: https://stackoverflow.com/questions/2746692/restructuredtext-tool-support

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 <https://sphinx-rtd-tutorial.readthedocs.io/en/latest/build-the-docs.html#generating-documentation-from-docstrings>`_. 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_

.. _ReText-wiki: https://github.com/retext-project/retext/wiki


Stuff from the original page
----------------------------
- kept to show some other 'directives' like 

 :class:`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

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