# sphinx-markdown-parser
A `docutils`-compatibility bridge to MarkdownParser and CommonMark.
This allows you to write markdown inside of docutils & sphinx projects.
This was built due to limitations of the existing markdown parsers
supported by sphinx, specifically recommonmark. Features such as support
for tables have been added to this extension.
Contents
--------
* [API Reference](docs/api_ref.md)
* [AutoStructify Component](docs/auto_structify.md)
## Recommended Projects
* [sphinx-markdown-builder](https://github.com/codejamninja/sphinx-markdown-builder) - sphinx builder that outputs markdown files
## Parsers
The `MarkdownParser` is the recommonend parser for the following reasons.
* It has more features such as tables and extensions
* It is the parser officially supported by this project
If you insist on using the `CommonMarkParser` I recommnend using [recommonmark](https://github.com/readthedocs/recommonmark) directly since we do not officially support that parser.
| **Parser** | **Source** |
| ------------------ | ------------------------------------------- |
| `MarkdownParser` | https://github.com/Python-Markdown/markdown |
| `CommonMarkParser` | https://github.com/readthedocs/recommonmark |
## Getting Started
To use `sphinx-markdown-parser` inside of Sphinx only takes 2 steps.
First you install it:
```
pip install sphinx-markdown-parser
```
If using MarkdownParser, you may also want to install some extensions for it:
```
pip install pymdown-extensions
```
Then add this to your Sphinx conf.py:
```
# for MarkdownParser
from sphinx_markdown_parser.parser import MarkdownParser
def setup(app):
app.add_source_suffix('.md', 'markdown')
app.add_source_parser(MarkdownParser)
app.add_config_value('markdown_parser_config', {
'auto_toc_tree_section': 'Content',
'enable_auto_doc_ref': True,
'enable_auto_toc_tree': True,
'enable_eval_rst': True,
'extensions': [
'extra',
'nl2br',
'sane_lists',
'smarty',
'toc',
'wikilinks',
'pymdownx.arithmatex',
],
}, True)
# for CommonMarkParser
from recommonmark.parser import CommonMarkParser
def setup(app):
app.add_source_suffix('.md', 'markdown')
app.add_source_parser(CommonMarkParser)
app.add_config_value('markdown_parser_config', {
'auto_toc_tree_section': 'Content',
'enable_auto_doc_ref': True,
'enable_auto_toc_tree': True,
'enable_eval_rst': True,
'enable_inline_math': True,
'enable_math': True,
}, True)
```
In order to use reStructuredText in Markdown (for `enable_eval_rst` to work properly), you must add AutoStructify in `conf.py`
```
# At top on conf.py
from sphinx_markdown_parser.transform import AutoStructify
# in setup function after configuration of the parser
app.add_transform(AutoStructify)
```
This allows you to write both `.md` and `.rst` files inside of the same project.
### Links
For all links in commonmark that aren't explicit URLs, they are treated as cross references with the [`:any:`](http://www.sphinx-doc.org/en/stable/markup/inline.html#role-any) role. This allows referencing a lot of things including files, labels, and even objects in the loaded domain.
### AutoStructify
AutoStructify makes it possible to write your documentation in Markdown, and automatically convert this
into rST at build time. See [the AutoStructify Documentation](http://recommonmark.readthedocs.org/en/latest/auto_structify.html)
for more information about configuration and usage.
To use the advanced markdown to rst transformations you must add `AutoStructify` to your Sphinx conf.py.
```python
# At top on conf.py (with other import statements)
from sphinx_markdown_parser.transform import AutoStructify
# At the bottom of conf.py
def setup(app):
app.add_config_value('markdown_parser_config', {
'url_resolver': lambda url: github_doc_root + url,
'auto_toc_tree_section': 'Contents',
}, True)
app.add_transform(AutoStructify)
```
See https://github.com/rtfd/recommonmark/blob/master/docs/conf.py for a full example.
AutoStructify comes with the following options. See [http://recommonmark.readthedocs.org/en/latest/auto_structify.html](http://recommonmark.readthedocs.org/en/latest/auto_structify.html) for more information about the specific features.
* __enable_auto_toc_tree__: enable the Auto Toc Tree feature.
* __auto_toc_tree_section__: when True, Auto Toc Tree will only be enabled on section that matches the title.
* __enable_auto_doc_ref__: enable the Auto Doc Ref feature. **Deprecated**
* __enable_math__: enable the Math Formula feature.
* __enable_inline_math__: enable the Inline Math feature.
* __enable_eval_rst__: enable the evaluate embedded reStructuredText feature.
* __url_resolver__: a function that maps a existing relative position in the document to a http link
## 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`.
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]: https://commonmark.org
[pcm]: https://github.com/rtfd/CommonMark-py
[rmd]: https://github.com/sgenoud/remarkdown
[prs]: https://github.com/pyga/parsley
[lu-zero]: https://github.com/lu-zero
[dc]: https://docutils.sourceforge.io/docs/ref/doctree.html
[sphinx-issue]: https://bitbucket.org/birkenfeld/sphinx/issue/825/markdown-capable-sphinx
[so-question]: https://stackoverflow.com/questions/2471804/using-sphinx-with-markdown-instead-of-rst
Raw data
{
"_id": null,
"home_page": "https://github.com/codejamninja/sphinx-markdown-parser",
"name": "sphinx-markdown-parser",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "sphinx docs documentation markdown",
"author": "Jam Risser",
"author_email": "jam@codejam.ninja",
"download_url": "https://files.pythonhosted.org/packages/bb/fa/83b286f823513a9ca3cfea4e04c8709083a308734bf1f7535a94a7f96df8/sphinx_markdown_parser-0.2.4.tar.gz",
"platform": "",
"description": "# sphinx-markdown-parser\n\nA `docutils`-compatibility bridge to MarkdownParser and CommonMark.\n\nThis allows you to write markdown inside of docutils & sphinx projects.\n\nThis was built due to limitations of the existing markdown parsers\nsupported by sphinx, specifically recommonmark. Features such as support\nfor tables have been added to this extension.\n\nContents\n--------\n\n* [API Reference](docs/api_ref.md)\n* [AutoStructify Component](docs/auto_structify.md)\n\n## Recommended Projects\n\n* [sphinx-markdown-builder](https://github.com/codejamninja/sphinx-markdown-builder) - sphinx builder that outputs markdown files\n\n## Parsers\n\nThe `MarkdownParser` is the recommonend parser for the following reasons.\n* It has more features such as tables and extensions\n* It is the parser officially supported by this project\n\nIf you insist on using the `CommonMarkParser` I recommnend using [recommonmark](https://github.com/readthedocs/recommonmark) directly since we do not officially support that parser.\n\n| **Parser** | **Source** |\n| ------------------ | ------------------------------------------- |\n| `MarkdownParser` | https://github.com/Python-Markdown/markdown |\n| `CommonMarkParser` | https://github.com/readthedocs/recommonmark |\n\n## Getting Started\n\nTo use `sphinx-markdown-parser` inside of Sphinx only takes 2 steps.\nFirst you install it:\n\n```\npip install sphinx-markdown-parser\n```\n\nIf using MarkdownParser, you may also want to install some extensions for it:\n\n```\npip install pymdown-extensions\n```\n\nThen add this to your Sphinx conf.py:\n\n```\n# for MarkdownParser\nfrom sphinx_markdown_parser.parser import MarkdownParser\n\ndef setup(app):\n app.add_source_suffix('.md', 'markdown')\n app.add_source_parser(MarkdownParser)\n app.add_config_value('markdown_parser_config', {\n 'auto_toc_tree_section': 'Content',\n 'enable_auto_doc_ref': True,\n 'enable_auto_toc_tree': True,\n 'enable_eval_rst': True,\n 'extensions': [\n 'extra',\n 'nl2br',\n 'sane_lists',\n 'smarty',\n 'toc',\n 'wikilinks',\n 'pymdownx.arithmatex',\n ],\n }, True)\n\n# for CommonMarkParser\nfrom recommonmark.parser import CommonMarkParser\n\ndef setup(app):\n app.add_source_suffix('.md', 'markdown')\n app.add_source_parser(CommonMarkParser)\n app.add_config_value('markdown_parser_config', {\n 'auto_toc_tree_section': 'Content',\n 'enable_auto_doc_ref': True,\n 'enable_auto_toc_tree': True,\n 'enable_eval_rst': True,\n 'enable_inline_math': True,\n 'enable_math': True,\n }, True)\n```\nIn order to use reStructuredText in Markdown (for `enable_eval_rst` to work properly), you must add AutoStructify in `conf.py`\n```\n# At top on conf.py\nfrom sphinx_markdown_parser.transform import AutoStructify\n\n# in setup function after configuration of the parser\napp.add_transform(AutoStructify)\n```\n\nThis allows you to write both `.md` and `.rst` files inside of the same project.\n\n### Links\n\nFor all links in commonmark that aren't explicit URLs, they are treated as cross references with the [`:any:`](http://www.sphinx-doc.org/en/stable/markup/inline.html#role-any) role. This allows referencing a lot of things including files, labels, and even objects in the loaded domain.\n\n### AutoStructify\n\nAutoStructify makes it possible to write your documentation in Markdown, and automatically convert this\ninto rST at build time. See [the AutoStructify Documentation](http://recommonmark.readthedocs.org/en/latest/auto_structify.html)\nfor more information about configuration and usage.\n\nTo use the advanced markdown to rst transformations you must add `AutoStructify` to your Sphinx conf.py.\n\n```python\n# At top on conf.py (with other import statements)\nfrom sphinx_markdown_parser.transform import AutoStructify\n\n# At the bottom of conf.py\ndef setup(app):\n app.add_config_value('markdown_parser_config', {\n 'url_resolver': lambda url: github_doc_root + url,\n 'auto_toc_tree_section': 'Contents',\n }, True)\n app.add_transform(AutoStructify)\n```\n\nSee https://github.com/rtfd/recommonmark/blob/master/docs/conf.py for a full example.\n\nAutoStructify comes with the following options. See [http://recommonmark.readthedocs.org/en/latest/auto_structify.html](http://recommonmark.readthedocs.org/en/latest/auto_structify.html) for more information about the specific features.\n\n* __enable_auto_toc_tree__: enable the Auto Toc Tree feature.\n* __auto_toc_tree_section__: when True, Auto Toc Tree will only be enabled on section that matches the title.\n* __enable_auto_doc_ref__: enable the Auto Doc Ref feature. **Deprecated**\n* __enable_math__: enable the Math Formula feature.\n* __enable_inline_math__: enable the Inline Math feature.\n* __enable_eval_rst__: enable the evaluate embedded reStructuredText feature.\n* __url_resolver__: a function that maps a existing relative position in the document to a http link\n\n## Development\n\nYou can run the tests by running `tox` in the top-level of the project.\n\nWe are working to expand test coverage,\nbut this will at least test basic Python 2 and 3 compatability.\n\n## Why a bridge?\n\nMany python tools (mostly for documentation creation) rely on `docutils`.\nBut [docutils][dc] only supports a ReStructuredText syntax.\n\nFor instance [this issue][sphinx-issue] and [this StackOverflow\nquestion][so-question] show that there is an interest in allowing `docutils`\nto use markdown as an alternative syntax.\n\n## Why another bridge to docutils?\n\nrecommonmark uses the [python implementation][pcm] of [CommonMark][cm] while\n[remarkdown][rmd] implements a stand-alone parser leveraging [parsley][prs].\n\nBoth output a [`docutils` document tree][dc] and provide scripts\nthat leverage `docutils` for generation of different types of documents.\n\n## Acknowledgement\n\nrecommonmark is mainly derived from [remarkdown][rmd] by Steve Genoud and\nleverages the python CommonMark implementation.\n\nIt was originally created by [Luca Barbato][lu-zero],\nand is now maintained in the Read the Docs (rtfd) GitHub organization.\n\n[cm]: https://commonmark.org\n[pcm]: https://github.com/rtfd/CommonMark-py\n[rmd]: https://github.com/sgenoud/remarkdown\n[prs]: https://github.com/pyga/parsley\n[lu-zero]: https://github.com/lu-zero\n\n[dc]: https://docutils.sourceforge.io/docs/ref/doctree.html\n[sphinx-issue]: https://bitbucket.org/birkenfeld/sphinx/issue/825/markdown-capable-sphinx\n[so-question]: https://stackoverflow.com/questions/2471804/using-sphinx-with-markdown-instead-of-rst",
"bugtrack_url": null,
"license": "MIT",
"summary": "A docutils-compatibility bridge to markdown, enabling you to write markdown with support for tables inside of docutils & sphinx projects.",
"version": "0.2.4",
"project_urls": {
"Homepage": "https://github.com/codejamninja/sphinx-markdown-parser"
},
"split_keywords": [
"sphinx",
"docs",
"documentation",
"markdown"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "7a0e63e90ae67eeeb6a5969deeccf0ac0d0c8d3252b9ce2eca7bd0a53aa3a651",
"md5": "009b107a248723ddc1fa6644e8124d99",
"sha256": "c9df4ab10d38d00e142ecb5542764b3470caa7f2339de33398df55b3a22b6a12"
},
"downloads": -1,
"filename": "sphinx_markdown_parser-0.2.4-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "009b107a248723ddc1fa6644e8124d99",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": null,
"size": 19174,
"upload_time": "2020-09-21T13:45:44",
"upload_time_iso_8601": "2020-09-21T13:45:44.438307Z",
"url": "https://files.pythonhosted.org/packages/7a/0e/63e90ae67eeeb6a5969deeccf0ac0d0c8d3252b9ce2eca7bd0a53aa3a651/sphinx_markdown_parser-0.2.4-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "bbfa83b286f823513a9ca3cfea4e04c8709083a308734bf1f7535a94a7f96df8",
"md5": "3acf994f8006f50d22b4e42d75af9227",
"sha256": "d91ac6f1db28bcc5d9061502f6fc2f6a23cc929d432b728acf4f64cdaa260bb3"
},
"downloads": -1,
"filename": "sphinx_markdown_parser-0.2.4.tar.gz",
"has_sig": false,
"md5_digest": "3acf994f8006f50d22b4e42d75af9227",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 43204,
"upload_time": "2020-09-21T13:41:06",
"upload_time_iso_8601": "2020-09-21T13:41:06.538864Z",
"url": "https://files.pythonhosted.org/packages/bb/fa/83b286f823513a9ca3cfea4e04c8709083a308734bf1f7535a94a7f96df8/sphinx_markdown_parser-0.2.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2020-09-21 13:41:06",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "codejamninja",
"github_project": "sphinx-markdown-parser",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [
{
"name": "Markdown",
"specs": [
[
">=",
"3.1.1"
]
]
},
{
"name": "commonmark",
"specs": [
[
">=",
"0.9.0"
]
]
},
{
"name": "pydash",
"specs": [
[
">=",
"4.7.5"
]
]
},
{
"name": "pyyaml",
"specs": [
[
">=",
"5.1.2"
]
]
},
{
"name": "sphinx",
"specs": [
[
">=",
"2.2.0"
]
]
},
{
"name": "unify",
"specs": [
[
">=",
"0.5"
]
]
},
{
"name": "yapf",
"specs": [
[
">=",
"0.28.0"
]
]
}
],
"tox": true,
"lcname": "sphinx-markdown-parser"
}
JSON
