AutoStructify Component
***********************

AutoStructify is a component in recommonmark that takes a parsed
docutil AST by "CommonMarkParser", and transform it to another AST
that introduces some of more. This enables additional features of
recommonmark syntax, to introduce more structure into the final
generated document.


Configuring AutoStructify
=========================

The behavior of AutoStructify can be configured via a dict in document
setting. In sphinx, you can configure it by "conf.py". The following
snippet is what is actually used to generate this document, see full
code at conf.py.

   github_doc_root = 'https://github.com/rtfd/recommonmark/tree/master/doc/'
   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)

All the features are by default enabled

***List of options***

* **enable_auto_toc_tree**: whether enable Auto Toc Tree feature.

* **auto_toc_tree_section**: when enabled,  Auto Toc Tree will only be
  enabled on section that matches the title.

* **enable_auto_doc_ref**: whether enable Auto Doc Ref feature.
  **Deprecated**

* **enable_math**: whether enable Math Formula

* **enable_inline_math**: whether enable Inline Math

* **enable_eval_rst**: whether Embed reStructuredText is enabled.

* **url_resolver**: a function that maps a existing relative position
  in the document to a http link


Auto Toc Tree
=============

One of important command in tools like sphinx is "toctree". This is a
command to generate table of contents and tell sphinx about the
structure of the documents. In markdown, usually we manually list of
contents by a bullet list of url reference to the other documents.

AutoStructify transforms bullet list of document URLs like this

   * [Title1](doc1.md)
   * [Title2](doc2.md)

to the AST of this following reStructuredText code

   .. toctree::
      :maxdepth: 1

      doc1
      doc2

You can also find the usage of this feature in "index.md" of this
document.


Auto Doc Ref
============

Note:

  **This option is deprecated.** This option has been superseded by
  the default linking behavior, which will first try to resolve as an
  internal reference, and then as an external reference.

It is common to refer to another document page in one document. We
usually use reference to do that. AutoStructify will translate these
reference block into a structured document reference. For example

   [API Reference](api_ref.md)

will be translated to the AST of following reStructuredText code

   :doc:`API Reference </api_ref>`

And it will be rendered as API Reference


URL Resolver
============

Sometimes in a markdown, we want to refer to the code in the same
repo. This can usually be done by a reference by reference path.
However, since the generated document is hosted elsewhere, the
relative path may not work in generated document site. URL resolver is
introduced to solve this problem.

Basically, you can define a function that maps an relative path of
document to the http path that you wish to link to. For example, the
setting  mentioned in the beginning of this document used a resolver
that maps the files to github. So "[parser
code](../recommonmark/parser.py)" will be translated into parser code

Note that the reference to the internal document will not be passed to
url resolver, and will be linked to the internal document pages
correctly, see Auto Doc Ref.


Codeblock Extensions
====================

In markdown, you can write codeblocks fenced by (at least) three
backticks ("```").  The following is an example of codeblock.

   ``` language
   some code block
   ```

Codeblock extensions are mechanism that specialize certain codeblocks
to different render behaviors. The extension will be trigger by the
language argument to the codeblck


Syntax Highlight
----------------

You can highlight syntax of codeblocks by specifying the language you
need. For example,

   ```python
   def function():
       return True
   ```

will be rendered as

   def function():
       return True


Math Formula
------------

You can normally write latex math formula with "math" codeblock. See
also Inline Math.

**Warning**: Math is currently broken on some Sphinx builds

Example

   ```math
   E = m c^2
   ```

will be rendered as

   E = m c^2


Embed reStructuredText
----------------------

Recommonmark also allows embedding reStructuredText syntax in the
codeblocks. There are two styles for embedding reStructuredText. The
first is enabled by "eval_rst" codeblock. The content of codeblock
will be parsed as reStructuredText and insert into the document. This
can be used to quickly introduce some of reStructuredText command that
not yet available in markdown. For example,

   ```eval_rst
   .. autoclass:: recommonmark.transform.AutoStructify
       :show-inheritance:
   ```

will be rendered as

class recommonmark.transform.AutoStructify(*args, **kwargs)

   Bases: "docutils.transforms.Transform"

   Automatically try to transform blocks to sphinx directives.

   This class is designed to handle AST generated by CommonMarkParser.

This example used to use sphinx autodoc to insert document of
AutoStructify class definition into the document.

The second style is a shorthand of the above style. It allows you to
leave off the eval_rst .. portion and directly render directives. For
example,

   ``` important:: Its a note! in markdown!
   ```

will be rendered as

Important:

  Its a note! in markdown!


An Advanced Example
~~~~~~~~~~~~~~~~~~~

   ``` sidebar:: Line numbers and highlights

        emphasis-lines:
          highlights the lines.
        linenos:
          shows the line numbers as well.
        caption:
          shown at the top of the code block.
        name:
          may be referenced with `:ref:` later.
   ```

   ``` code-block:: markdown
        :linenos:
        :emphasize-lines: 3,5
        :caption: An example code-block with everything turned on.
        :name: Full code-block example

        # Comment line
        import System
        System.run_emphasis_line
        # Long lines in code blocks create a auto horizontal scrollbar
        System.exit!
   ```

will be rendered as


Line numbers and highlights
^^^^^^^^^^^^^^^^^^^^^^^^^^^

emphasis-lines:
   highlights the lines.

linenos:
   shows the line numbers as well.

caption:
   shown at the top of the code block.

name:
   may be referenced with *:ref:* later.

An example code-block with everything turned on.

   # Comment line
   import System
   System.run_emphasis_line
   # Long lines in code blocks create a auto horizontal scrollbar
   System.exit!

The "<div style="clear: right;"></div>" line clears the sidebar for
the next title.


Inline Math
===========

Besides the Math Formula, you can also write latex math in inline
codeblock text. You can do so by inserting "$" in the beginning and
end of inline codeblock.

Example

**Warning**: Math is currently broken on some Sphinx builds

   This formula `$ y=\sum_{i=1}^n g(x_i) $`

will be rendered as:

This formula "$ y=\sum_{i=1}^n g(x_i) $"
