self document.

docs/conf.py

@@ -19,12 +19,13 @@ import shlex
 # 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.
-#sys.path.insert(0, os.path.abspath('.'))
-
+sys.path.insert(0, os.path.abspath('..'))
+import recommonmark
 from recommonmark.parser import CommonMarkParser
+from recommonmark.transform import AutoStructify
 
 source_parsers = {
-    '.md': CommonMarkParser,
+    '.md': CommonMarkParser
 }
 
 source_suffix = ['.rst', '.md']
@@ -37,7 +38,11 @@ source_suffix = ['.rst', '.md']
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
-extensions = []
+extensions = [
+    'sphinx.ext.autodoc',
+    'sphinx.ext.napoleon',
+    'sphinx.ext.mathjax',
+]
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
@@ -53,14 +58,16 @@ project = u'Recommonmark'
 copyright = u'2015, Lu Zero, Eric Holscher, and contributors'
 author = u'Lu Zero, Eric Holscher, and contributors'
 
+github_doc_root = 'https://github.com/rtfd/recommonmark/tree/master/doc/'
+
 # 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.0'
-# The full version, including alpha/beta/rc tags.
-release = '1.0'
+version = recommonmark.__version__
+# The full version, including alpha/beta/rc tagss
+release = recommonmark.__version__
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
@@ -285,3 +292,12 @@ texinfo_documents = [
 
 # If true, do not generate a @detailmenu in the "Top" node's menu.
 #texinfo_no_detailmenu = False
+
+# app setup hook
+def setup(app):
+    app.add_config_value('recommonmark_config', {
+            'url_resolver': lambda url: github_doc_root + url,
+            'auto_toc_tree_section': 'Contents',
+            }, True)
+    app.add_transform(AutoStructify)
+

docs/index.md

@@ -1,10 +1,22 @@
-# recommonmark
+Recommonmark
+============
 
 A `docutils`-compatibility bridge to [CommonMark][cm].
 
 This allows you to write CommonMark inside of Docutils & Sphinx projects.
 
-## Why a bridge?
+Contents
+--------
+* [API Reference](api_ref.md)
+* [AutoStructify Component](auto_structify.md)
+
+Getting Started
+---------------
+This document is actually generated by recommonmark, and its source code can be used as a good reference.
+To see what you can get beyond the normal markdown syntax, checkout [AutoStructify Component](auto_structify.md).
+
+Why a bridge?
+-------------
 
 Many python tools (mostly for documentation creation) rely on `docutils`.
 But [docutils][dc] only supports a ReStructuredText syntax.
@@ -21,7 +33,8 @@ recommonmark uses the [python implementation][pcm] of [CommonMark][cm] while
 Both output a [`docutils` document tree][dc] and provide scripts
 that leverage `docutils` for generation of different types of documents.
 
-## Acknowledgement
+Acknowledgement
+---------------
 
 recommonmark is mainly derived from [remarkdown][rmd] by Steve Genoud and
 leverages the python CommonMark implementation.

recommonmark/parser.py

@@ -38,6 +38,7 @@ class _SectionHandler(object):
 
 
 class CommonMarkParser(parsers.Parser):
+    """Parser of recommonmark."""
     supported = ('md', 'markdown')
 
     def convert_blocks(self, blocks):

recommonmark/transform.py

@@ -16,9 +16,10 @@ class AutoStructify(transforms.Transform):
 
     default_config = {
         'enable_auto_doc_ref': True,
+        'auto_toc_tree_section': None,
         'enable_auto_toc_tree': True,
         'enable_eval_rst': True,
-        'enable_math': False,
+        'enable_math': True,
         'url_resolver': lambda x: x,
         }
 
@@ -94,6 +95,20 @@ class AutoStructify(transforms.Transform):
         """
         if not self.config['enable_auto_toc_tree']:
             return None
+        # when auto_toc_tree_section is set
+        # only auto generate toctree under the specified section title
+        sec = self.config['auto_toc_tree_section']
+        if sec is not None:
+            if node.parent is None:
+                return None
+            if not isinstance(node.parent, nodes.section):
+                return None
+            title = node.parent.children[0]
+            if not isinstance(title, nodes.title):
+                return None
+            if title.astext().strip() != sec:
+                return None
+
         numbered = None
         if isinstance(node, nodes.bullet_list):
             numbered = 0
@@ -248,6 +263,7 @@ class AutoStructify(transforms.Transform):
         self.current_level = old_level
 
     def apply(self):
+        """Apply the transformation by configuration."""
         # only transform markdowns
         source = self.document['source']
         if not source.endswith('.md'):