Documenting configuration

Author: hardbyte

can/util.py

@@ -97,7 +97,7 @@ def load_config(path=None):
     The returned dictionary may look like this::
 
         {
-            'interface': '<python-can backend interface to use',
+            'interface': 'python-can backend interface to use',
             'channel': 'default channel to use',
         }
 
@@ -116,6 +116,7 @@ def load_config(path=None):
 
     return config
 
+
 def choose_socketcan_implementation():
     """Set the best version of SocketCAN for this system.
 

doc/api.rst

@@ -18,6 +18,14 @@ A form of CAN interface is also required.
    bcm
 
 
+
+Utilities
+---------
+
+.. automodule:: can.util
+    :members:
+
+
 .. _notifier:
 
 Notifier

doc/conf.py

@@ -3,16 +3,22 @@
 # python-can documentation build configuration file
 #
 # This file is execfile()d with the current directory set to its containing dir.
-#
-# Note that not all possible configuration values are present in this
-# autogenerated file.
-#
-# All configuration values have a default; values that are commented out
-# serve to show the default.
 
 import sys
 import os
 
+# General information about the project.
+project = u'python-can'
+
+# The version info for the project you're documenting, acts as replacement for
+# |version| and |release|, also used in various other places throughout the
+# built documents.
+#
+# The short X.Y version.
+version = '1.5'
+# The full version, including alpha/beta/rc tags.
+release = '1.5.2'
+
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
@@ -54,19 +60,6 @@
 # The master toctree document.
 master_doc = 'index'
 
-# General information about the project.
-project = u'python-can'
-
-copyright = u'2013 Dynamic Controls'
-
-# The version info for the project you're documenting, acts as replacement for
-# |version| and |release|, also used in various other places throughout the
-# built documents.
-#
-# The short X.Y version.
-version = '1.5'
-# The full version, including alpha/beta/rc tags.
-release = '1.5.2'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.

doc/configuration.rst

@@ -2,28 +2,30 @@ Configuration
 =============
 
 
+Usually this library is used with a particular CAN interface, this can be
+specified in code, read from configuration files or environment variables.
+
+See :func:`can.util.load_config` for implementation.
 
 In Code
 -------
 
-The ``can`` object exposes an ``rc`` dictionary which can be used to set the **interface**
-before importing from ``can.interfaces``.
+The ``can`` object exposes an ``rc`` dictionary which can be used to set
+the **interface** and **channel** before importing from ``can.interfaces``.
 
 ::
 
     import can
     can.rc['interface'] = 'socketcan'
+    can.rc['channel'] = 'vcan0'
     from can.interfaces.interface import Bus
-    can_interface = 'vcan0'
-    bus = Bus(can_interface)
+
+    bus = Bus()
 
 
 Configuration File
 ------------------
 
-Usually this library is used with a particular CAN interface, this can be specified in
-a configuration file.
-
 On Linux systems the config file is searched in the following paths:
 
 1. ``/etc/can.conf``
@@ -43,3 +45,35 @@ The configuration file sets the default interface and channel:
     interface = <the name of the interface to use>
     channel = <the channel to use by default>
 
+
+Environment Variables
+---------------------
+
+Configuration can be pulled from these environmental variables:
+
+    * CAN_INTERFACE
+    * CAN_CHANNEL
+
+
+Interface Names
+---------------
+
+Lookup table of interface names:
+
++---------------------+-------------------------------------+
+| Name                | Documentation                       |
++=====================+=====================================+
+| ``"socketcan"``     | :doc:`interfaces/socketcan`         |
++---------------------+-------------------------------------+
+| ``"kvaser"``        | :doc:`interfaces/kvaser`            |
++---------------------+-------------------------------------+
+| ``"serial"``        | :doc:`interfaces/serial`            |
++---------------------+-------------------------------------+
+| ``"ixxat"``         | :doc:`interfaces/ixxat`             |
++---------------------+-------------------------------------+
+| ``"pcan"``          | :doc:`interfaces/pcan`              |
++---------------------+-------------------------------------+
+| ``"usb2can"``       | :doc:`interfaces/usb2can`           |
++---------------------+-------------------------------------+
+| ``"virtual"``       | :doc:`interfaces/virtual`           |
++---------------------+-------------------------------------+

doc/interfaces.rst

@@ -6,25 +6,20 @@ area network adapters in interface dependant modules. However as each hardware
 device is different, you should carefully go through your interface's
 documentation.
 
-The interfaces currently available are:
-
-+---------------------+-------------------------------------+
-| Name                | Documentation                       |
-+=====================+=====================================+
-| ``"socketcan"``     | :doc:`interfaces/socketcan`         |
-+---------------------+-------------------------------------+
-| ``"kvaser"``        | :doc:`interfaces/kvaser`            |
-+---------------------+-------------------------------------+
-| ``"serial"``        | :doc:`interfaces/serial`            |
-+---------------------+-------------------------------------+
-| ``"ixxat"``         | :doc:`interfaces/ixxat`             |
-+---------------------+-------------------------------------+
-| ``"pcan"``          | :doc:`interfaces/pcan`              |
-+---------------------+-------------------------------------+
-| ``"usb2can"``       | :doc:`interfaces/usb2can`           |
-+---------------------+-------------------------------------+
-| ``"virtual"``       | :doc:`interfaces/virtual`           |
-+---------------------+-------------------------------------+
-
-The `Interface Name` is used in :doc:`configuration`.
+The available interfaces are:
+
+.. toctree::
+   :maxdepth: 1
+
+   interfaces/socketcan
+   interfaces/kvaser
+   interfaces/serial
+   interfaces/ixxat
+   interfaces/pcan
+   interfaces/usb2can
+   interfaces/virtual
+
+
+
+The *Interface Names* are listed in :doc:`configuration`.