Enhances sphinx documentation

Enhances documentation on source code Enhances load serial message action
pybpod · Jan 19, 2017 · 5488016 · 5488016
1 parent 2e3cb1a
commit 5488016
Show file tree

Hide file tree

Showing 16 changed files with 568 additions and 371 deletions.
diff --git a/docs/source/api_reference/com/arcom.rst b/docs/source/api_reference/com/arcom.rst
@@ -1,17 +1,19 @@
-*****************************
+=============================
 Arduino Communication Wrapper
-*****************************
+=============================
 
 .. contents:: Contents
     :local:
 
+--------
 Overview
-========
+--------
 
 TODO
 
+--------------
 Implementation
-==============
+--------------
 
 
 .. automodule:: pybpodapi.com.arcom

diff --git a/docs/source/api_reference/com/com.rst b/docs/source/api_reference/com/com.rst
diff --git a/docs/source/api_reference/com/hw_info_container.rst b/docs/source/api_reference/com/hw_info_container.rst
@@ -0,0 +1,23 @@
+=======================
+Hardware Info Container
+=======================
+
+.. contents:: Contents
+    :local:
+
+--------
+Overview
+--------
+
+This container is used to store hardware description received from Bpod device.
+After, this info will be used to fill the :class:`pybpodapi.hardware.hardwarw.Hardware` object.
+The reason to use this container is because :class:`pybpodapi.hardware.hardwarw.Hardware` does some initializations that depend on information collected from several protocol commands.
+
+--------------
+Implementation
+--------------
+
+
+.. automodule:: pybpodapi.com.hardware_info_container
+    :members:
+    :private-members:
diff --git a/docs/source/api_reference/com/index.rst b/docs/source/api_reference/com/index.rst
@@ -1,11 +1,13 @@
-Communication
-=============
+**********************
+Communication Protocol
+**********************
 
 Contents:
 
 .. toctree::
    :maxdepth: 2
 
-   com
    protocol
-   arcom
+   message_headers
+   arcom
+   hw_info_container
diff --git a/docs/source/api_reference/com/message_headers.rst b/docs/source/api_reference/com/message_headers.rst
@@ -0,0 +1,23 @@
+========================
+Protocol Message Headers
+========================
+
+.. contents:: Contents
+    :local:
+
+--------
+Overview
+--------
+
+The protocol to talk with Bpod device is defined by the Arduino firmware version installed.
+
+Each message sent or received from Bpod contains a header which is the first byte (character). This header defines the type of action that should be executed.
+
+--------------
+Implementation
+--------------
+
+
+.. automodule:: pybpodapi.com.message_headers
+    :members:
+    :private-members:
diff --git a/docs/source/api_reference/com/protocol.rst b/docs/source/api_reference/com/protocol.rst
@@ -1,19 +1,20 @@
-**********************
-Communication Protocol
-**********************
+=================
+Protocol Commands
+=================
 
 .. contents:: Contents
     :local:
 
+--------
 Overview
-========
+--------
 
-TODO
+This module defines protocol commands that are available to interact with the Bpod device.
 
+--------------
 Implementation
-==============
+--------------
 
-
-.. automodule:: pybpodapi.com.bpod_protocol
+.. automodule:: pybpodapi.com.protocol
     :members:
     :private-members:
diff --git a/docs/source/api_reference/index.rst b/docs/source/api_reference/index.rst
@@ -1,5 +1,6 @@
+###############
 Model Reference
-===============
+###############
 
 Contents:
 

diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -48,6 +48,9 @@
     'sphinx.ext.todo',
     'sphinx.ext.viewcode']
 
+# Do not sort autodoc alphabetically, use source code appearance order
+autodoc_member_order= 'bysource'
+
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
 
@@ -192,4 +195,4 @@
 
 
 # Example configuration for intersphinx: refer to the Python standard library.
-intersphinx_mapping = {'https://docs.python.org/': None}
+intersphinx_mapping = {'https://docs.python.org/3/': None}