python/python-recommonmark
SHA256
14
0
Fork 0
forked from pool/python-recommonmark
Code Pull Requests Activity

Accepting request 486216 from home:TheBlackCat:branches:devel:languages:python

Browse Source 
- Remove README since the upstream link changes unpredictably and there is no consistent way to pick a particular version.

OBS-URL: https://build.opensuse.org/request/show/486216
OBS-URL: https://build.opensuse.org/package/show/devel:languages:python/python-recommonmark?expand=0&rev=3
This commit is contained in:
Todd R
2017-04-06 17:45:53 +00:00
committed by Git OBS Bridge
parent fc93d4fd6e
commit 8cf5b317f9
3 changed files with 7 additions and 114 deletions
Download Patch File Download Diff File Expand all files Collapse all files

111
README.md
View File

@@ -1,111 +0,0 @@
# recommonmark
A `docutils`-compatibility bridge to [CommonMark][cm].
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.
First you install it:
```
pip install recommonmark
```
Then add this to your Sphinx conf.py:
```
from recommonmark.parser import CommonMarkParser
source_parsers = {
'.md': CommonMarkParser,
}
source_suffix = ['.rst', '.md']
```
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
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)
import recommonmark
from recommonmark.transform import AutoStructify
# At the bottom of conf.py
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)
```
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 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.
* __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]: http://commonmark.org
[pcm]: https://github.com/rtfd/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

6
python-recommonmark.changes
View File

@@ -1,3 +1,9 @@
-------------------------------------------------------------------
Thu Apr 6 17:42:45 UTC 2017 - toddrme2178@gmail.com
- Remove README since the upstream link changes unpredictably and
there is no consistent way to pick a particular version.
-------------------------------------------------------------------
Mon Apr 3 14:53:38 UTC 2017 - toddrme2178@gmail.com

4
python-recommonmark.spec
View File

@@ -26,7 +26,6 @@ Group: Development/Languages/Python
Url: https://github.com/rtfd/recommonmark
Source0: https://files.pythonhosted.org/packages/source/r/recommonmark/recommonmark-%{version}.tar.gz
Source1: https://raw.githubusercontent.com/rtfd/recommonmark/master/license.md
Source2: https://raw.githubusercontent.com/rtfd/recommonmark/master/README.md
BuildRequires: fdupes
BuildRequires: python-rpm-macros
BuildRequires: %{python_module devel}
@@ -59,7 +58,6 @@ http://recommonmark.readthedocs.org
rm -rf %{pypi_name}.egg-info
#Add missing license and readme
cp -a %{SOURCE1} .
cp -a %{SOURCE2} .
# find and remove unneeded shebangs
find recommonmark -name "*.py" | xargs sed -i '1 {/^#!/ d}'
@@ -89,7 +87,7 @@ find recommonmark -name "*.py" | xargs sed -i '1 {/^#!/ d}'
%files %{python_files}
%defattr(-,root,root,-)
%doc README.md license.md
%doc license.md
%python_alternative %{_bindir}/cm2html
%python_alternative %{_bindir}/cm2latex
%python_alternative %{_bindir}/cm2man