Reorganizes API reference

Adds class diagram Adds sequence diagram for Bpod.start
pybpod · Jan 20, 2017 · 0ddcd1e · 0ddcd1e
1 parent a494147
commit 0ddcd1e
Show file tree

Hide file tree

Showing 24 changed files with 149 additions and 108 deletions.
diff --git a/docs/source/_images/main_classes.png b/docs/source/_images/main_classes.png
diff --git a/docs/source/_images/sd_bpod_start.png b/docs/source/_images/sd_bpod_start.png
diff --git a/docs/source/api_reference/com/index.rst b/docs/source/api_reference/com/index.rst
diff --git a/docs/source/api_reference/hardware/index.rst b/docs/source/api_reference/hardware/index.rst
diff --git a/docs/source/api_reference/index.rst b/docs/source/api_reference/index.rst
@@ -1,12 +1,17 @@
-###############
-Model Reference
-###############
+#############
+API Reference
+#############
 
-Contents:
+**Modules Hierarchy**
 
 .. toctree::
    :maxdepth: 2
+   :titlesonly:
+
+   pybpodapi/index
+
+**Principal Classes (and modules)**
+
+.. image:: /_images/main_classes.png
+   :scale: 100 %
 
-   model/index
-   hardware/index
-   com/index
diff --git a/docs/source/api_reference/model/index.rst b/docs/source/api_reference/model/index.rst
diff --git a/docs/source/api_reference/model/session.rst b/docs/source/api_reference/model/session.rst
diff --git a/docs/source/api_reference/model/trial.rst b/docs/source/api_reference/model/trial.rst
diff --git a/docs/source/api_reference/model/bpod.rst → docs/source/api_reference/pybpodapi/bpod.rst b/docs/source/api_reference/model/bpod.rst → docs/source/api_reference/pybpodapi/bpod.rst
@@ -1,11 +1,11 @@
 .. _bpod-class-label:
 
-====
-Bpod
-====
+*******************
+:mod:`bpod`--- Bpod
+*******************
 
-.. contents:: Contents
-    :local:
+.. module:: bpod
+   :synopsis: Bpod main module
 
 Overview
 --------

diff --git a/docs/source/api_reference/com/arcom.rst → ...rce/api_reference/pybpodapi/com/arcom.rst b/docs/source/api_reference/com/arcom.rst → ...rce/api_reference/pybpodapi/com/arcom.rst
diff --git a/...e/api_reference/com/hw_info_container.rst → ...rence/pybpodapi/com/hw_info_container.rst b/...e/api_reference/com/hw_info_container.rst → ...rence/pybpodapi/com/hw_info_container.rst
@@ -1,9 +1,6 @@
-=======================
-Hardware Info Container
-=======================
-
-.. contents:: Contents
-    :local:
+==========================================================
+:mod:`hardware_info_container` --- Hardware Info Container
+==========================================================
 
 --------
 Overview

diff --git a/docs/source/api_reference/pybpodapi/com/index.rst b/docs/source/api_reference/pybpodapi/com/index.rst
@@ -0,0 +1,15 @@
+***************************
+:mod:`com`--- Communication
+***************************
+
+.. module:: pybpodapi.com
+   :synopsis: communication with Bpod device
+
+.. toctree::
+   :titlesonly:
+
+   protocol
+   message_headers
+   arcom
+   hw_info_container
+   serial_message_container
diff --git a/...rce/api_reference/com/message_headers.rst → ...ference/pybpodapi/com/message_headers.rst b/...rce/api_reference/com/message_headers.rst → ...ference/pybpodapi/com/message_headers.rst
@@ -1,9 +1,6 @@
-========================
-Protocol Message Headers
-========================
-
-.. contents:: Contents
-    :local:
+===================================================
+:mod:`message_headers` --- Protocol Message Headers
+===================================================
 
 --------
 Overview

diff --git a/docs/source/api_reference/com/protocol.rst → .../api_reference/pybpodapi/com/protocol.rst b/docs/source/api_reference/com/protocol.rst → .../api_reference/pybpodapi/com/protocol.rst
@@ -1,6 +1,9 @@
-===========================
-Requesting Commands to Bpod
-===========================
+===============================================
+:mod:`protocol` --- Requesting Commands to Bpod
+===============================================
+
+.. module:: com.protocol
+   :synopsis: communication with Bpod device
 
 .. contents:: Contents
     :local:

diff --git a/...eference/com/serial_message_container.rst → ...ybpodapi/com/serial_message_container.rst b/...eference/com/serial_message_container.rst → ...ybpodapi/com/serial_message_container.rst
diff --git a/docs/source/api_reference/pybpodapi/hardware/hardware.rst b/docs/source/api_reference/pybpodapi/hardware/hardware.rst
@@ -0,0 +1,20 @@
+========================================================
+:mod:`hardware` --- Hardware Description For Bpod Device
+========================================================
+
+.. module:: pybpodapi.hardware.hardware
+   :synopsis: bpod device hardware description
+
+--------
+Overview
+--------
+
+Hardware description ...
+
+--------------
+Implementation
+--------------
+
+.. autoclass:: pybpodapi.hardware.hardware.Hardware
+    :members:
+    :private-members:
diff --git a/docs/source/api_reference/pybpodapi/hardware/index.rst b/docs/source/api_reference/pybpodapi/hardware/index.rst
@@ -0,0 +1,11 @@
+***************************
+:mod:`hardware`--- Hardware
+***************************
+
+.. module:: pybpodapi.hardware
+   :synopsis: communication with Bpod device
+
+.. toctree::
+   :titlesonly:
+
+   hardware
diff --git a/docs/source/api_reference/pybpodapi/index.rst b/docs/source/api_reference/pybpodapi/index.rst
@@ -0,0 +1,20 @@
+*************************************
+:mod:`pybpodapi`--- pybpod-api module
+*************************************
+
+.. module:: pybpodapi
+   :synopsis: top-level module
+
+.. toctree::
+   :titlesonly:
+
+   bpod
+   state_machine
+   session
+   trial
+   hardware/index
+   com/index
+
+**Start Bpod Sequence Diagram**
+
+.. image:: /_images/sd_bpod_start.png
diff --git a/docs/source/api_reference/pybpodapi/session.rst b/docs/source/api_reference/pybpodapi/session.rst
@@ -0,0 +1,18 @@
+*************************
+:mod:`session`--- Session
+*************************
+
+.. module:: session
+   :synopsis: session to run on bpod
+
+Overview
+--------
+
+TODO
+
+Implementation
+--------------
+
+.. autoclass:: pybpodapi.model.session.Session
+    :members:
+    :private-members:
diff --git a/...rce/api_reference/model/state_machine.rst → ...api_reference/pybpodapi/state_machine.rst b/...rce/api_reference/model/state_machine.rst → ...api_reference/pybpodapi/state_machine.rst
@@ -1,9 +1,9 @@
-*************
-State Machine
-*************
+*************************************
+:mod:`state_machine`--- State Machine
+*************************************
 
-.. contents:: Contents
-    :local:
+.. module:: state_machine
+   :synopsis: modules related to state machine
 
 Overview
 ========

diff --git a/docs/source/api_reference/pybpodapi/trial.rst b/docs/source/api_reference/pybpodapi/trial.rst
@@ -0,0 +1,19 @@
+*********************
+:mod:`trial`--- Trial
+*********************
+
+.. module:: trial
+   :synopsis: A session trial
+
+Overview
+========
+
+TODO
+
+Implementation
+==============
+
+
+.. automodule:: pybpodapi.model.trial
+    :members:
+    :private-members:
diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -75,9 +75,9 @@
 # built documents.
 #
 # The short X.Y version.
-version = '0.1'
+version = '0.2'
 # The full version, including alpha/beta/rc tags.
-release = '0.1'
+release = 'v0.2'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.

diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -14,6 +14,7 @@ Welcome to pybpod-api's documentation!
 
 .. toctree::
    :maxdepth: 4
+   :includehidden:
 
    getting_started
    writing_protocols

diff --git a/pybpodapi/model/bpod.py b/pybpodapi/model/bpod.py
@@ -20,7 +20,7 @@
 
 class Bpod(object):
 	"""
-	Bpod main class
+	Bpod is the main entity.
 	"""
 
 	#########################################
@@ -43,6 +43,14 @@ def hardware(self):
 	def hardware(self, value):
 		self._hardware = value  # type: Hardware
 
+	@property
+	def bpod_protocol(self):
+		return self._bpod_protocol  # type: Protocol
+
+	@bpod_protocol.setter
+	def bpod_protocol(self, value):
+		self._bpod_protocol = value  # type: Protocol
+
 	#########################################
 	############ PUBLIC METHODS #############
 	#########################################