hiro/recommonmark
1
0
Fork 0
mirror of https://github.com/vale981/recommonmark synced 2025-03-04 17:41:38 -05:00
Code Issues Projects Releases Packages Wiki Activity Actions

Symlink readme to doc index

Browse source
This commit is contained in:
Eric Holscher 2015-10-19 14:13:45 -07:00
parent a9b9dbe01f
commit 4a0915e28b
2 changed files with 13 additions and 55 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

12
README.md
View file

@ -6,6 +6,11 @@ This allows you to write CommonMark inside of Docutils & Sphinx projects.
Documentation is available on Read the Docs: <http://recommonmark.readthedocs.org>
Contents
--------
* [API Reference](api_ref.md)
* [AutoStructify Component](auto_structify.md)
## Getting Started
To use `recommonmark` inside of Sphinx only takes 2 steps.
@ -25,6 +30,13 @@ Then add this to your Sphinx conf.py:
This allows you to write both `.md` and `.rst` files inside of the same project.
## Development
You can run the tests by running `tox` in the top-level of the project.
We are working to expand test coverage,
but this will at least test basic Python 2 and 3 compatability.
## Why a bridge?
Many python tools (mostly for documentation creation) rely on `docutils`.

55
docs/index.md
View file

@ -1,55 +0,0 @@
Recommonmark
============
A `docutils`-compatibility bridge to [CommonMark][cm].
This allows you to write CommonMark inside of Docutils & Sphinx projects.
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.
[AutoStructify Component](auto_structify.md) provides a lot of additional features beyond markdown,
including reference generation, syntax hightlight and math formula.
Why a bridge?
-------------
Many python tools (mostly for documentation creation) rely on `docutils`.
But [docutils][dc] only supports a ReStructuredText syntax.
For instance [this issue][sphinx-issue] and [this StackOverflow
question][so-question] show that there is an interest in allowing `docutils`
to use markdown as an alternative syntax.
## Why another bridge to docutils?
recommonmark uses the [python implementation][pcm] of [CommonMark][cm] while
[remarkdown][rmd] implements a stand-alone parser leveraging [parsley][prs].
Both output a [`docutils` document tree][dc] and provide scripts
that leverage `docutils` for generation of different types of documents.
Acknowledgement
---------------
recommonmark is mainly derived from [remarkdown][rmd] by Steve Genoud and
leverages the python CommonMark implementation.
It was originally created by [Luca Barbato][lu-zero],
and is now maintained in the Read the Docs (rtfd) GitHub organization.
[cm]: http://commonmark.org
[pcm]: https://github.com/rolandshoemaker/CommonMark-py
[rmd]: https://github.com/sgenoud/remarkdown
[prs]: https://github.com/python-parsley/parsley
[lu-zero]: https://github.com/lu-zero
[dc]: http://docutils.sourceforge.net/docs/ref/doctree.html
[sphinx-issue]: https://bitbucket.org/birkenfeld/sphinx/issue/825/markdown-capable-sphinx
[so-question]: http://stackoverflow.com/questions/2471804/using-sphinx-with-markdown-instead-of-rst

1
docs/index.md Symbolic link
View file

@ -0,0 +1 @@
../README.md