path: root/python-sphinx-markdown-parser.spec

%global _empty_manifest_terminate_build 0
Name:		python-sphinx-markdown-parser
Version:	0.2.4
Release:	1
Summary:	A docutils-compatibility bridge to markdown, enabling you to write markdown with support for tables inside of docutils & sphinx projects.
License:	MIT
URL:		https://github.com/codejamninja/sphinx-markdown-parser
Source0:	https://mirrors.nju.edu.cn/pypi/web/packages/bb/fa/83b286f823513a9ca3cfea4e04c8709083a308734bf1f7535a94a7f96df8/sphinx_markdown_parser-0.2.4.tar.gz
BuildArch:	noarch


%description
* [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

%package -n python3-sphinx-markdown-parser
Summary:	A docutils-compatibility bridge to markdown, enabling you to write markdown with support for tables inside of docutils & sphinx projects.
Provides:	python-sphinx-markdown-parser
BuildRequires:	python3-devel
BuildRequires:	python3-setuptools
BuildRequires:	python3-pip
%description -n python3-sphinx-markdown-parser
* [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

%package help
Summary:	Development documents and examples for sphinx-markdown-parser
Provides:	python3-sphinx-markdown-parser-doc
%description help
* [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

%prep
%autosetup -n sphinx-markdown-parser-0.2.4

%build
%py3_build

%install
%py3_install
install -d -m755 %{buildroot}/%{_pkgdocdir}
if [ -d doc ]; then cp -arf doc %{buildroot}/%{_pkgdocdir}; fi
if [ -d docs ]; then cp -arf docs %{buildroot}/%{_pkgdocdir}; fi
if [ -d example ]; then cp -arf example %{buildroot}/%{_pkgdocdir}; fi
if [ -d examples ]; then cp -arf examples %{buildroot}/%{_pkgdocdir}; fi
pushd %{buildroot}
if [ -d usr/lib ]; then
	find usr/lib -type f -printf "/%h/%f\n" >> filelist.lst
fi
if [ -d usr/lib64 ]; then
	find usr/lib64 -type f -printf "/%h/%f\n" >> filelist.lst
fi
if [ -d usr/bin ]; then
	find usr/bin -type f -printf "/%h/%f\n" >> filelist.lst
fi
if [ -d usr/sbin ]; then
	find usr/sbin -type f -printf "/%h/%f\n" >> filelist.lst
fi
touch doclist.lst
if [ -d usr/share/man ]; then
	find usr/share/man -type f -printf "/%h/%f.gz\n" >> doclist.lst
fi
popd
mv %{buildroot}/filelist.lst .
mv %{buildroot}/doclist.lst .

%files -n python3-sphinx-markdown-parser -f filelist.lst
%dir %{python3_sitelib}/*

%files help -f doclist.lst
%{_docdir}/*

%changelog
* Fri May 05 2023 Python_Bot <Python_Bot@openeuler.org> - 0.2.4-1
- Package Spec generated