rviz_python_tutorial: added sphinx documentation describing tutorial contents.

Author: hershwg

rviz_python_tutorial/config.myviz

@@ -1,3 +1,4 @@
+Title: RViz Python Tutorial
 Panels:
   []
 Visualization Manager:

rviz_python_tutorial/doc-src/conf.py

@@ -0,0 +1,25 @@
+import sys, os
+
+sys.path += [ os.path.abspath( '.' )]
+
+extensions = [ 'sphinx.ext.extlinks',
+               'tutorialformatter' ]
+
+# The master toctree document.
+master_doc = 'index'
+
+# The suffix of source filenames.
+source_suffix = '.rst'
+
+project = u'rviz_python_tutorial'
+
+copyright = u'2012,  Willow Garage, Inc'
+
+# If true, sectionauthor and moduleauthor directives will be shown in the
+# output. They are ignored by default.
+show_authors = True
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = 'sphinx'
+
+extlinks = {'srcdir': ('https://github.com/ros-visualization/visualization_tutorials/blob/groovy-devel/rviz_python_tutorial/%s', '')}

rviz_python_tutorial/doc-src/index.rst

@@ -0,0 +1,48 @@
+RViz Python Tutorial
+====================
+
+Overview
+--------
+
+RViz is not just a visualizer application, it is also a Python
+library!  Much of RViz's functionality can be accessed from Python
+code by importing the librviz Python bindings.
+
+This tutorial shows a simple example of creating a visualizer
+(rviz::VisualizationFrame) as a child widget along with other Qt
+widgets, programmatically loading a config file, then connecting a
+slider and some Qt push buttons to change display a display property
+and the viewpoint.
+
+The source code for this tutorial is in the rviz_python_tutorial
+package. You can check out the source directly or (if you use Ubuntu)
+you can just apt-get install the pre-compiled Debian package like so::
+
+    sudo apt-get install ros-groovy-visualization-tutorials
+
+The running application looks like this:
+
+.. image:: myviz.png
+
+The Code: myviz.py
+------------------
+
+The full text of myviz.py is here: :srcdir:`myviz.py`
+
+.. tutorial-formatter:: ../myviz.py
+
+Running
+-------
+
+Just type::
+
+    roscd rviz_python_tutorial
+    ./myviz.py
+
+myviz.py loads its config file from the current directory, so you need
+to run it from the directory it comes in, or adapt the script to find
+the file.
+
+There are more classes in RViz which do not yet have Python bindings.
+If you find important ones are missing, please request them as
+"enhancement" issues on the RViz project on github.

rviz_python_tutorial/doc-src/myviz.png

@@ -0,0 +1,132 @@
+"""
+    tutorialformatter
+    ===========================
+
+    This extension provides a directive to include a source code file
+    in a document, but with certain comments from the file formatted
+    as regular document text.  This allows code for a tutorial to look like:
+
+        /// BEGIN_TUTORIAL
+        /// This next line adds one.
+        i = i + 1;
+        /// Then we need to double it.
+        i = i * 2;
+        /// END_TUTORIAL
+
+    And have it formatted as
+
+    This next line adds one.::
+        i = i + 1;
+
+    Then we need to double it.::
+        i = i * 2;
+
+    The special-looking comment character sequence at the start of
+    each text line can be anything not starting or ending with
+    whitespace.  tutorialformatter starts by scanning the file for the
+    string BEGIN_TUTORIAL.  When it finds it, it takes all the
+    characters before BEGIN_TUTORIAL on that line, strips whitespace
+    from the left, and uses that as the text marker.  So this would
+    also be fine:
+
+        #My Tutorial# BEGIN_TUTORIAL
+        #My Tutorial# This next line adds one.
+        i = i + 1
+        #My Tutorial# Then we need to double it.
+        i = i * 2
+        #My Tutorial# END_TUTORIAL
+
+    .. moduleauthor::  Dave Hershberger <[email protected]>
+"""
+
+__version__ = '0.1.0'
+
+import os
+from docutils.parsers import rst
+from docutils.parsers.rst.directives import flag, unchanged
+from docutils.statemachine import string2lines
+from pygments.lexers import get_lexer_for_filename
+
+class TutorialFormatterDirective(rst.Directive):
+    has_content = False
+    final_argument_whitespace = True
+    required_arguments = 1
+
+    option_spec = dict(shell=flag, prompt=flag, nostderr=flag,
+                       in_srcdir=flag, extraargs=unchanged,
+                       until=unchanged)
+
+    def run(self):
+        filename = self.arguments[0]
+        text_tag = None
+        tag_len = 0
+
+        filepath = self.state.document.settings.env.srcdir
+        absfilename = os.path.join( filepath, filename )
+        if absfilename.endswith('.h'):
+            language = 'c++'
+        elif absfilename.endswith('CMakeLists.txt'):
+            language = 'cmake'
+        else:
+            try:
+                language = get_lexer_for_filename( absfilename ).name.lower()
+                if language == 'text only':
+                    language = 'none'
+            except:
+                language = 'none'
+        code_prefix = '\n.. code-block:: ' + language + '\n\n'
+        code_suffix = '\n'
+
+        print "tutorial-formatter running on", absfilename
+        file_ = open( absfilename, 'r' )
+        text_to_process = ""
+        current_block = ""
+        in_code = False
+        in_text = False
+        in_tutorial = False
+        for line in file_:
+            if not in_tutorial:
+                begin_pos = line.find( 'BEGIN_TUTORIAL' )
+                if begin_pos != -1:
+                    text_tag = line[:begin_pos].lstrip()
+                    tag_len = len( text_tag )
+                    in_tutorial = True
+                continue
+            if line.find( 'END_TUTORIAL' ) != -1:
+                break
+            stripped = line.lstrip()
+            if stripped.startswith( text_tag.strip() ):
+                if in_code:
+                    text_to_process += code_prefix + current_block + code_suffix
+                    current_block = ""
+                    in_code = False
+                in_text = True
+                addition = stripped[tag_len:]
+                if addition == '' or addition[-1] != '\n':
+                    addition += '\n'
+                current_block += addition
+            else:
+                if in_text:
+                    text_to_process += current_block
+                    current_block = ""
+                    in_text = False
+                    in_code = True # Code to show begins right after tagged text
+                if in_code:
+                    current_block += ' ' + line
+        if in_code:
+            text_to_process += code_prefix + current_block + code_suffix
+        elif in_text:
+            text_to_process += current_block
+
+        # Debug writes...
+        #print 'text_to_process ='
+        #print text_to_process
+        #print '= text_to_process'
+
+        lines = string2lines( text_to_process )
+        self.state_machine.insert_input( lines, absfilename )
+
+        return []
+
+def setup(app):
+    app.add_directive('tutorial-formatter', TutorialFormatterDirective)