miyakogi / m2r

Markdown to reStructuredText converter

NO MORE UPDATES

Feel free to fork and update.

---

Old README

M2R

---

M2R converts a markdown file including reStructuredText (rst) markups to a valid rst format.

Why another converter?

I wanted to write sphinx document in markdown, since it's widely used now and easy to write code blocks and lists. However, converters using pandoc or recommonmark do not support many rst markups and sphinx extensions. For example, rst's reference link like see `ref`_ (this is very convenient in long document in which same link appears multiple times) will be converted to a code block in HTML like see <code>ref</code>_, which is not expected.

Features

• Basic markdown and some extensions (see below)
  • inline/block-level raw html
  • fenced-code block
  • tables
  • footnotes ([^1])
• Inline- and Block-level rst markups
  • single- and multi-line directives (.. directive::)
  • inline-roles (:code:`print(1)` ...)
  • ref-link (see `ref`_)
  • footnotes ([#fn]_)
  • math extension inspired by recommonmark
• Sphinx extension
  • add markdown support for sphinx
  • mdinclude directive to include markdown from md or rst files
  • option to parse relative links into ref and doc directives (m2r_parse_relative_links)
• Pure python implementation
  • pandoc is not required

Installation

Python 3.7+ is required.

pip install m2r

Or,

python3 -m pip install m2r

Usage

Command Line

m2r command converts markdown file to rst format.

m2r your_document.md [your_document2.md ...]

Then you will find your_document.rst in the same directory.

Programmatic Use

Import m2r.convert function and call it with markdown text. Then it will return converted text.

from m2r import convert
rst = convert('# Title\n\nSentence.')
print(rst)
# Title
# =====
#
# Sentence.

Or, use parse_from_file function to load markdown file and obtain converted text.

from m2r import parse_from_file
output = parse_from_file('markdown_file.md')

This is an example of setup.py to write README in markdown, and publish it to PyPI as rst format.

readme_file = os.path.join(os.path.dirname(os.path.abspath(__file__)), 'README.md')
try:
    from m2r import parse_from_file
    readme = parse_from_file(readme_file)
except ImportError:
    # m2r may not be installed in user environment
    with open(readme_file) as f:
        readme = f.read()
setup(
    ...,
    long_description=readme,
    ...,
)

Sphinx Integration

In your conf.py, add the following lines.

extensions = [
    ...,
    'm2r',
]

# source_suffix = '.rst'
source_suffix = ['.rst', '.md']

Write index.md and run make html.

When m2r extension is enabled on sphinx and .md file is loaded, m2r converts to rst and pass to sphinx, not making new .rst file.

mdinclude directive

Like .. include:: file directive, .. mdinclude:: file directive inserts markdown file at the line.

Note: do not use .. include:: file directive to include markdown file even if in the markdown file, please use .. mdinclude:: file instead.

Restrictions

• In the rst's directives, markdown is not available. Please write in rst.
• Column alignment of tables is not supported. (rst does not support this feature)
• Heading with overline-and-underline is not supported.
  • Heading with underline is OK
• Rst heading marks are currently hard-coded and unchangeable.
  • H1: =, H2: -, H3: ^, H4: ~, H5: ", H6: #

If you find any bug or unexpected behaviour, please report it to Issues.

Example

See example document and its source code.

I'm using m2r for writing user guide of WDOM. So you can see it as another example. Its HTML is here, and its source code is here.

Demo editor

Demo editor of m2r is available. If you are interested in m2r, please try it.

https://github.com/miyakogi/m2rdemo

Acknowledgement

m2r is written as an extension of mistune, which is highly extensible pure-python markdown parser. Without the mistune, I couldn't write this. Thank you!

Licence

MIT

m2r's Issues

Support $$ for math

An alternative to

```math
c^2
```

is

$$
c^2
$$

I am used to the second one as that's what my editor uses.
Maybe m2r could support multiple math markup. If the user does the markup consistently in the Markdown file, this process could be automated.

(WARNING/2) Title underline too short.

hi,
When i execute the 'make html' command prompt me:
`WARNING: error_doc.md:3: (WARNING/2) Title underline too short.
三、错误对照表

This is the contents of error_doc.md

三、错误对照表

错误码	错误名称	Message	说明
0	Api Runtime Error	Runtime api error occurred.

I do not know whether it is caused by Chinese, Hope to get your help.

                                                                                                                                         Thanks!                

body of spoiler is rendered incorrectly

markdown:

<details>
<summary>summary</summary>
    
```python
foo = 1 + 1
```
</details>

example is rendered into valid spoiler but its body is just plain text instead of code block.

---

life example:

• markdown (search for "argparse alternative" string)
• rendered

Incorrect table conversion

First of all, thank you for creating and supporting m2r! Really appreciate it.

That said, I am trying to convert the following (extracted) markdown file into rst.

| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| foo   | bar |  |  |

<a name="test"/>

The generated table is missing a row and will cause errors along the lines of Error parsing content block for the "list-table" directive: uniform two-level bullet list expected, but row 2 does not contain the same number of items as row 1 (3 vs 4). This happens because the generated output looks like:

.. role:: raw-html-m2r(raw)
   :format: html


.. list-table::
   :header-rows: 1

   * - Field
     - Type
     - Label
     - Description
   * - foo
     - bar
     -


:raw-html-m2r:`<a name="test"/>`

and is missing the fourth row in the table. However, if the last line of the markdown is removed, the problem disappers. I am using m2r 0.1.14.

Document header level scheme used in rst output.

The header level scheme is defined in m2r.py#L177-L184. However, if a parent rst file uses a different scheme and then "mincludes" a Markdown file, there is likely to be a Title level inconsistent error. At the very least, it should be documented that the parent rst file needs to use the same scheme (= for level 1, - for level 2, etc.).

For example, this should work fine:

Parent Header
=============

.. minclude:: child.md

Whereas this would likely raise a Title level inconsistent error:

Parent Header
-------------

.. minclude:: child.md

See this for an actual report in the wild.

As a reminder, the reStructuredText Spec explains:

Rather than imposing a fixed number and order of section title adornment styles, the order enforced will be the order as encountered. The first style encountered will be an outermost title (like HTML H1), the second style will be a subtitle, the third will be a subsubtitle, and so on.

...

All section title styles need not be used, nor need any specific section title style be used. However, a document must be consistent in its use of section titles: once a hierarchy of title styles is established, sections must use that hierarchy.

Therefore, the parent document could use any number of different schemes by ordering there headers differently, Of course, the parent and child (when including one document in another) must be consistent. However, as users of M2R are not directly authoring the child document as rst, they would not know what scheme is being used. At the least it should be documented. As best, M2R could detect the scheme used in the parent file and use that same scheme when generating the included child.

Support of mermaid blocks in .md files

I've noticed an issue when trying to convert a .md file with mermaid code.
Mermaid is widely used in Markdown file and works well. Also mermaid support already added to Sphinx using the sphinxcontrib-mermaid plugin. Mermaid markup in a .rst file is look as below:

.. mermaid::

   sequenceDiagram
      participant Alice
      participant Bob
      Alice->John: Hello John, how are you?
      loop Healthcheck
          John->John: Fight against hypochondria
      end
      Note right of John: Rational thoughts <br/>prevail...
      John-->Alice: Great!
      John->Bob: How about you?
      Bob-->John: Jolly good!

But seems during composing the documentation from a .md file Sphinx not able to recognize mermaid markup because M2R converted 1st line of mermaid block not into .. mermaid:: string but into .. code-block:: mermaid string.
Could you please add conversion of mermaid block not as code-block but as separate and specific code?

Make RestRenderer.hmarks not hardcoded

I'm trying to refactor the Jupyterlab docs to use mdinclude as part of jupyterlab/jupyterlab#8246. Our current rst header mark scheme does not match the hardcoded one in m2r, and it's proving to be a pain point. Rather than having to write crazy looking regexes (eg (?<=^~*)~(?!\s\S+)) to replace my header marks, it would be much nicer if I could just configure m2r.

I'm happy to submit a PR for this. Before I jump in and work on it though, I'd like to clarify: is there a reason why the header marks in RestRenderer.hmarks are hardcoded? Or can they just be set freely?

[PyPi] md2rst parsing problem

I'm using m2r for parse my README.md file and after publication on pypi formatting just broke.

my parser code in setup.py

try:
    from m2r import parse_from_file

    LONG_DESCRIPTION = parse_from_file('README.md')
except ImportError:
    with open('README.md') as f:
        LONG_DESCRIPTION = f.read()

0.2.1: pytest is sometimes failing when `pytest-randomly` is installed

Looks like there are some test units order dependecies and ~2-3 out of 10 tries fails usually with:

+ /usr/bin/pytest -ra
=========================================================================== test session starts ============================================================================
platform linux -- Python 3.8.11, pytest-6.2.4, py-1.10.0, pluggy-0.13.1
benchmark: 3.4.1 (defaults: timer=time.perf_counter disable_gc=False min_rounds=5 min_time=0.000005 max_time=1.0 calibration_precision=10 warmup=False warmup_iterations=100000)
Using --randomly-seed=2348392663
rootdir: /home/tkloczko/rpmbuild/BUILD/m2r-0.2.1
plugins: forked-1.3.0, shutil-1.7.0, virtualenv-1.7.0, expect-1.1.0, flake8-1.0.7, timeout-1.4.2, betamax-0.8.1, freezegun-0.4.2, aspectlib-1.5.2, toolbox-0.5, rerunfailures-9.1.1, requests-mock-1.9.3, cov-2.12.1, pyfakefs-4.5.0, flaky-3.7.0, benchmark-3.4.1, xdist-2.3.0, pylama-7.7.1, datadir-1.3.1, regressions-2.2.0, cases-3.6.3, xprocess-0.18.1, black-0.3.12, anyio-3.3.0, Faker-8.11.0, asyncio-0.15.1, trio-0.7.0, httpbin-1.0.0, subtests-0.5.0, isort-2.0.0, hypothesis-6.14.6, mock-3.6.1, profiling-1.7.0, randomly-3.8.0, checkdocs-2.7.1
collected 86 items

tests/test_cli.py ......                                                                                                                                             [  6%]
. .                                                                                                                                                                  [  8%]
tests/test_cli.py ...                                                                                                                                                [ 11%]
tests/test_renderer.py ...........s.........................F......................................                                                                  [100%]

================================================================================= FAILURES =================================================================================
___________________________________________________________________ TestInlineMarkdown.test_inline_math ____________________________________________________________________

self = <tests.test_renderer.TestInlineMarkdown testMethod=test_inline_math>

    def test_inline_math(self):
        src = 'this is `$E = mc^2$` inline math.'
        out = self.conv(src)
>       self.assertEqual(out, '\nthis is :math:`E = mc^2` inline math.\n')
E       AssertionError: '\nthis is ``$E = mc^2$`` inline math.\n' != '\nthis is :math:`E = mc^2` inline math.\n'
E
E       - this is ``$E = mc^2$`` inline math.
E       ?          --        - -
E       + this is :math:`E = mc^2` inline math.
E       ?         ++++++

tests/test_renderer.py:292: AssertionError
========================================================================= short test summary info ==========================================================================
SKIPPED [1] tests/test_renderer.py:323: markdown does not support dedent in block quote
FAILED tests/test_renderer.py::TestInlineMarkdown::test_inline_math - AssertionError: '\nthis is ``$E = mc^2$`` inline math.\n' != '\nthis is :math:`E = mc^2` inline mat...
================================================================= 1 failed, 84 passed, 1 skipped in 7.98s ==================================================================
pytest-xprocess reminder::Be sure to terminate the started process by running 'pytest --xkill' if you have not explicitly done so in your fixture with 'xprocess.getinfo(<pr

Workaround: run pytest -p no:randomly
To diagnose this issue can be used https://github.com/mrbean-bremen/pytest-find-dependencies/

Sphinx 1.8.0 incompatibility

I've added 'm2r' as described to the sphinx extensions list, source_suffix got also reviewed accordingly.

extensions = [
    'sphinx.ext.autodoc',
    'sphinx.ext.intersphinx',
    'sphinxcontrib.log_cabinet',
    'm2r'
]

source_suffix = ['.rst', '.md']

Then I get the following error when I trigger the documentation generator.

Extension error:
source_parser for 'restructuredtext' is already registered
Makefile:22: recipe for target 'html' failed
make: *** [html] Error 2

$ sphinx-apidoc --version
sphinx-apidoc 1.8.0+

'm2r' got installed by using pip3.

$ pip3 install m2r

Support for 'title' in links

The conversion of markdown links with title does not work:

[http://localhost:8888](http://localhost:8888 "Jupyter Notebook")

Link not parsed correctly if wrapped around less-than/greater-than signs

In some cases, when a link in markdown is wrapped around less-than and greater-than signs (<, >), it is not parsed properly and the rendered output is wrong.

Consider a markdown file with the following content:

<[GitHub](https://github.com)>

The rendered output straight from markdown is:

<GitHub>

Passing the file to m2r, I am expecting the output to be:

<`GitHub <https://github.com>`_>

However the actual output is:

[GitHub](https://github.com)

hyperlinking to a header within the same markdown page breaks the id of the header

I've noticed an issue when trying to link to a section within the same markdown file breaks the id.

For example, if I have this section:

## Current Trends

The link to it will be #current-trends. If however, I add this at the top of the page:

* [Current Trends](#current-trends)

the link to that header now becomes #id1.

From doing a few tests, it looks like its the text used for the hyperlink that causes issues. So because I set the link text to Current Trends and the header has the same name, it breaks it. I could use * [Current Trends](#id1) and it would work. But I'd like the header ids to have meaning

incorrect conversion of code block with comments mis-converted to headers

Take the following code snippet for example:

import supy as sp
import matplotlib.pyplot as plt

#load sample data

#load sample data will be converted a level one header.

This is an unexpected behaviour.

Bug: block directive at the end of file

Block directive at the end of file fails convertsion.

.. directive::
    something
<empty lines>

When convert the above, directive body becomes empty.

Image link in markdown with relative link not working with sphinx

I have markdown files that reference png images in a separate folder. When viewing / editing those markdown files, all works fine having a relative image link.

However, when the file is converted using sphinx, the only way I can get sphinx to find the images is by changing the paths relative to where sphinx.

For instance, my original markdown file has

![](assets/2019-10-23-13-49-56.png)

In order for the sphinx conversion process to recognize it, I have to change it to

![](../../Gitlab/assets/2019-10-23-13-49-56.png)

The updated location now references from the sphinx execution point, rather than from the markdown file. But doing in doing so, I can allow Sphinx to find the link. Otherwise, I get a warning from Sphinx in the first link above that it cannot find the file:

WARNING: image file not readable: ./assets/2019-10-23-13-49-56.png

Is there a way for image links to comprehend the shift in relative paths, based on the root location of the markdown file that is being processed from?

Python3.10: TestConvert::test_no_file - AssertionError: 'optional arguments:' not found in 'usage: m2r.py

When runing tests with Python 3.10.0b1 I get the following test failure:

=========================================================== FAILURES ===========================================================
___________________________________________________ TestConvert.test_no_file ___________________________________________________

self = <tests.test_cli.TestConvert testMethod=test_no_file>

    def test_no_file(self):
        p = subprocess.Popen(
            [sys.executable, '-m', 'm2r'],
            stdout=subprocess.PIPE,
        )
        p.wait()
        self.assertEqual(p.returncode, 0)
        with p.stdout as buffer:
            message = buffer.read().decode()
        self.assertIn('usage', message)
        self.assertIn('underscore-emphasis', message)
        self.assertIn('anonymous-references', message)
        self.assertIn('inline-math', message)
>       self.assertIn('optional arguments:', message)
E       AssertionError: 'optional arguments:' not found in 'usage: m2r.py [-h] [--overwrite] [--dry-run] [--no-underscore-emphasis] [--parse-relative-links] [--anonymous-references]\n              [--disable-inline-math]\n              [input_file ...]\n\npositional arguments:\n  input_file            files to convert to reST format\n\noptions:\n  -h, --help            show this help message and exit\n  --overwrite           overwrite output file without confirmaion\n  --dry-run             print conversion result and not save output file\n  --no-underscore-emphasis\n                        do not use underscore (_) for emphasis\n  --parse-relative-links\n                        parse relative links into ref or doc directives\n  --anonymous-references\n                        use anonymous references in generated rst\n  --disable-inline-math\n                        disable parsing inline math\n'

buffer     = <_io.BufferedReader name=11>
message    = ('usage: m2r.py [-h] [--overwrite] [--dry-run] [--no-underscore-emphasis] '
 '[--parse-relative-links] [--anonymous-references]\n'
 '              [--disable-inline-math]\n'
 '              [input_file ...]\n'
 '\n'
 'positional arguments:\n'
 '  input_file            files to convert to reST format\n'
 '\n'
 'options:\n'
 '  -h, --help            show this help message and exit\n'
 '  --overwrite           overwrite output file without confirmaion\n'
 '  --dry-run             print conversion result and not save output file\n'
 '  --no-underscore-emphasis\n'
 '                        do not use underscore (_) for emphasis\n'
 '  --parse-relative-links\n'
 '                        parse relative links into ref or doc directives\n'
 '  --anonymous-references\n'
 '                        use anonymous references in generated rst\n'
 '  --disable-inline-math\n'
 '                        disable parsing inline math\n')
p          = <Popen: returncode: 0 args: ['/usr/bin/python3.10', '-m', 'm2r']>
self       = <tests.test_cli.TestConvert testMethod=test_no_file>

tests/test_cli.py:62: AssertionError

AttributeError: module 'mistune' has no attribute 'BlockGrammar' in line 58 of m2r.py

When packaging new version of mistune (2.0.0-rc1) is included into openSUSE/Factory, this package’s test suite starts failing:

[   32s] + /usr/bin/python3.6 setup.py build '--executable=/usr/bin/python3.6 -s'
[   32s] Traceback (most recent call last):
[   32s]   File "setup.py", line 14, in <module>
[   32s]     from m2r import parse_from_file
[   32s]   File "/home/abuild/rpmbuild/BUILD/m2r-0.2.1/m2r.py", line 58, in <module>
[   32s]     class RestBlockGrammar(mistune.BlockGrammar):
[   32s] AttributeError: module 'mistune' has no attribute 'BlockGrammar'
[   32s] error: Bad exit status from /var/tmp/rpm-tmp.G27V7P (%build)

Complete build log with all versions of packages used and steps taken.

Image Directive :target: Broken

Problem

The image() function generates the RST directive which includes the :target: attribute. Since Sphinx copies all images to /_images, any images in subfolders will have a broken link using :target: which which include the subdirectory path. Since the :target: attribute still references the relative path based on the source directory and not the /_images directory, clicking the links generates a 404.

Example Output of Broken href

You can see the difference in paths. the href path will not exists. In source, these images are in a subdirectory.

<a class="reference external image-reference" href="../_images/curl_jokes_json.gif"><img alt="cURL with JSON" src="../../_images/curl_jokes_json.gif" /></a>

Possible Fix

Since it seems that Sphinx always copies all images to the /_images folder, modifying the method like this could work:

def image(self, src, title, text):
        """Rendering a image with title and text.

        :param src: source link of the image.
        :param title: title text of the image.
        :param text: alt text of the image.
        """

        image_name = os.path.basename(src)
        target = f"/_images/{image_name}"

        # rst does not support title option
        # and I couldn't find title attribute in HTML standard
        return '\n'.join([
            '',
            '.. image:: {}'.format(src),
            '   :target: {}'.format(target),
            '   :alt: {}'.format(text),
            '',
        ])

Essentially, parsing the filename from the original source and generating target based on where we know sphinx is going to put the images.

arguments for mdinclude directive

if was just playing around with things as we run into an issue with multiple headlines (one from .md file and one in .rst file), but we want to keep the .rst headline.

.. mdinclude:: ../HISTORY.md
   :lines: 2-

This results into

home/kai/git/python-sdk/docs/changelog.rst:4: WARNING: Error in "mdinclude" directive:
maximum 1 argument(s) allowed, 3 supplied.

.. mdinclude:: ../HISTORY.md
   :lines: 2-

Would be very great if mdinclude could support also some of the arguments that are available on the literalinclude directive. Let me know if you plan to work on this or not.
Thanks a lot :)

(Sphinx) How to link to markdown files

In your example from https://raw.githubusercontent.com/miyakogi/m2r/master/docs/example.md:

Link to [document](example.md) in markdown.

links propertly to example.html (that is auto-generated without additional rst file I suppose)

For me such a link points to .md file (not to generated html file), that not exists in build directory of course. I've played around with m2r_parse_relative_links but this searches for relative links from the "source" sphinx folder and it breaks normal anchors in .md

What have I missed?

part of docs/conf.py

sys.path.append(os.path.abspath(os.path.join('..', '..', 'src')))
extensions = [
    'sphinx.ext.autodoc',
    'sphinx_autodoc_typehints',
    'm2r'  # mdinclude directive for makrdown files
]
autodoc_member_order = 'bysource'
autodoc_inherit_docstrings = False
autodoc_mock_imports = ["galaxy.http"]

source_suffix = ['.rst', '.md']
master_doc = 'index'

README.md

[Link](another.md)

docs/source/index.rst

Title
=================================================

.. toctree::

   Overview <overview>

docs/source/overview.rst

.. mdinclude:: ../../README.md

docs/make.py

subprocess.run(['sphinx-build', '-M', 'html', 'docs/source', 'docs/build'])

my ugly workaround

docs/source/overview.rst

.. mdinclude:: ../../README.md
   :end-line: 26

:ref:`link`

.. mdinclude:: ../../README.md
    :start-line: 28

docs/source/link.rst

.. _link:

.. mdinclude:: ../../PLATFORM_IDs.md

Anything like `eval_rst`

Hi!

I started using this instead of recommonmark mainly because of the .. mdinclude directive. It's great work, thanks!

Only thing that I miss is having something like:

```eval_rst
```

...as a scape hatch to be able to freely write rst code in the middle of a document. I tried to find it but failed. Is there anything like it in this library?

MD table not translating correctly when last cell is empty

a	b
k	l
m

| a   | b   |  
| --- | --- | 
| k   | l   | 
| m   |     | 

does not get translated by m2r correctly, resulting in errors in Sphinx:

 WARNING: Error parsing content block for the "list-table" directive: uniform two-level bullet list expected, but row 3 does not contain the same number of items as row 1 (1 vs 2).

.. list-table::
   :header-rows: 1

   * - a
     - b
   * - k
     - l
   * - m

The table

a	b
k
m	n

| a   | b   |
| --- | --- |
| k   |     |
| m   | n   |

is handled correctly by m2r.

The following table also produces Sphinx errors:

a	b
k
m	n

| a   | b   |
| --- | --- |
| k   |   
| m   | n   |

while

a	b
k	p
m	n

| a   | b   |
| --- | --- |
| k   | p  
| m   | n   |

works.

WARNING: Duplicate explicit target name: "here"

I have two [here](...) in the document, then I see

../../README.md:3: WARNING: Duplicate explicit target name: "here".
../../README.md:3: WARNING: Duplicate explicit target name: "here".

Can we emit anonymous reference instead?

Code Block Within Ordered List Doesn't Render Properly

Summary

If you create an ordered list (1, 2, 3, etc.) and embed a code block within it, even if it renders properly for the vast majority of Markdown editors/previewers, m2R either doesn't translate/render the code block correctly, or the numbering starts over if you format the Markdown so that it will render the code block correctly.

Reference Examples

Here's an example of a Markdown snippet that has an ordered list which includes a code block within it:

1. Open a terminal
2. Change to your favorite directory (i.e. `cd /opt`)
3. Clone the repository

```bash 
git clone git@someaccount/somerepo.git
```

4. Do the next thing you do

Expected Rendering Below

This renders (via most Markdown previewers, etc.) to:

---

1. Open a terminal
2. Change to your favorite directory (i.e. cd /opt)
3. Clone the repository

git clone git@someaccount/somerepo.git

4. Do the next thing you do

---

The equivalent reStructuredText block which would achieve the same thing would be:

#. Open a terminal
#. Change to your favorite directory (i.e. `cd /opt`)
#. Clone the repository

    .. code-block:: bash

      git clone git@someaccount/somerepo.git

#. Do the next thing you do

I've verified with Sphinx that the above does render the above code block pretty much as the section I've marked as Expected Rendering Below.

So - I know that it's possible to have an inline code block within an ordered list.

Issues

One is faced with a devil's dilemma - either have the code block rendered correctly and break the list "chain" and start a new ordinal sequence, or keep the ordinal chain sequence and have the code block not render correctly.

Approach 1 - Keep Order, Lose Code Block Rendering

If you format your Markdown as shown below, you'll keep your ordering...

1. Open a terminal
2. Change to your favorite directory (i.e. `cd /opt`)
3. Clone the repository
```bash 
git clone git@someaccount/somerepo.git
```
4. Do the next thing you do

...but it gets rendered like this (notice the `` .. code-block:: bash` at the end of line 3):

---

1. Open a terminal
2. Change to your favorite directory (i.e. cd /opt)
3. Clone the repository .. code-block:: bash

git clone git@someaccount/somerepo.git

4. Do the next thing you do

---

Approach 2 - Lose Order, Gain Code Block Rendering

If you have a Markdown snippet as seen above in Reference Examples, you'll get a rendering like this:

---

1. Open a terminal
2. Change to your favorite directory (i.e. cd /opt)
3. Clone the repository

git clone git@someaccount/somerepo.git

1. Do the next thing you do

---

Conclusion

I cannot find a reasonable compromise between maintaining an ordinal list and having a code block within it render properly. I'm forced to choose between a properly-rendered code block or a properly ordered list.

Note that I can provide screen shots and extra examples as needed.

Deprecation Warning: add_source_parser

During the build process, the following warning is emitted:

/opt/conda/lib/python3.7/site-packages/m2r.py:652: RemovedInSphinx30Warning: app.add_source_parser() does not support suffix argument. Use app.add_source_suffix() instead.

Looks like some functionality will be removed in the next version of sphinx. I found this on version 2.2.1

Question: relative path links in markdown

I have an MD project I want to generate HTMLs for.
In the root README.md file I have [manual](manual/) link, which should point to ./manual/README.md file. Instead, the link is to ./README/manual/ which is wrong (no need for the README at the start of the path)
Any way to bypass this issue without updating the doc source?

Missing Git tags for releases

It would be nice to keep PyPI releases and git tags in sync :)

Does not work with sphinx 3.5.1

# Sphinx version: 3.5.1
# Python version: 3.7.3 (CPython)
# Docutils version: 0.16 release
# Jinja2 version: 2.11.3
# Last messages:

# Loaded extensions:
Traceback (most recent call last):
  File "/home/nicoco/.cache/pypoetry/virtualenvs/pysignald-async-E_E3_Jap-py3.7/lib/python3.7/site-packages/sphinx/cmd/build.py", line 279, in build_main
    args.tags, args.verbosity, args.jobs, args.keep_going)
  File "/home/nicoco/.cache/pypoetry/virtualenvs/pysignald-async-E_E3_Jap-py3.7/lib/python3.7/site-packages/sphinx/application.py", line 245, in __init__
    self.setup_extension(extension)
  File "/home/nicoco/.cache/pypoetry/virtualenvs/pysignald-async-E_E3_Jap-py3.7/lib/python3.7/site-packages/sphinx/application.py", line 402, in setup_extension
    self.registry.load_extension(self, extname)
  File "/home/nicoco/.cache/pypoetry/virtualenvs/pysignald-async-E_E3_Jap-py3.7/lib/python3.7/site-packages/sphinx/registry.py", line 430, in load_extension
    metadata = setup(app)
  File "/home/nicoco/.cache/pypoetry/virtualenvs/pysignald-async-E_E3_Jap-py3.7/lib/python3.7/site-packages/m2r.py", line 652, in setup
    app.add_source_parser('.md', M2RParser)
  File "/home/nicoco/.cache/pypoetry/virtualenvs/pysignald-async-E_E3_Jap-py3.7/lib/python3.7/site-packages/sphinx/application.py", line 1204, in add_source_parser
    self.registry.add_source_parser(parser, override=override)
  File "/home/nicoco/.cache/pypoetry/virtualenvs/pysignald-async-E_E3_Jap-py3.7/lib/python3.7/site-packages/sphinx/registry.py", line 267, in add_source_parser
    for filetype in parser.supported:
AttributeError: 'str' object has no attribute 'supported'

mdinclude image path support

If a Markdown file is in a different directory and includes images, the paths are not preserved when the file is inserted into the source document.

For example:

.. mdinclude:: D:\Code\Fomu\foboot\hw\deps\valentyusb\valentyusb\usbcore\cpu\howto.md

❯ sphinx-build -M html build/documentation/ build/documentation/_build
Running Sphinx v2.2.0
c:\python37\lib\site-packages\m2r.py:652: RemovedInSphinx30Warning: app.add_source_parser() does not support suffix argument. Use app.add_source_suffix() instead.
app.add_source_parser('.md', M2RParser)
loading pickled environment... done
building [mo]: targets for 0 po files that are out of date
building [html]: targets for 0 source files that are out of date
updating environment: 0 added, 1 changed, 0 removed
reading sources... [100%] usb
deps/valentyusb/valentyusb/usbcore/cpu/howto.md:: WARNING: image file not readable: usb-icon.jpg
looking for now-outdated files... none found
pickling environment... done
checking consistency... D:\Code\Fomu\foboot\hw\build\documentation\identifier_mem.rst: WARNING: document isn't included in any toctree
D:\Code\Fomu\foboot\hw\build\documentation\lxspi.rst: WARNING: document isn't included in any toctree
done
preparing documents... done
writing output... [100%] usb
generating indices...  genindexdone
writing additional pages...  searchdone
copying static files... ... done
copying extra files... done
dumping search index in English (code: en)... done
dumping object inventory... done
build succeeded, 3 warnings.
The HTML pages are in build\documentation\_build\html.
smcro@CUBOID  D:\Code\Fomu\foboot\hw foboot-2 ≢ 
[13:51]  ❯ dir .\deps\valentyusb\valentyusb\usbcore\cpu\usb-icon.jpg
Directory: D:\Code\Fomu\foboot\hw\deps\valentyusb\valentyusb\usbcore\cpu
Mode                LastWriteTime         Length Name
----                -------------         ------ ----
-a----        24/9/2019  12:37 pm          15507 usb-icon.jpg
smcro@CUBOID  D:\Code\Fomu\foboot\hw   foboot-2 ≢ 
[13:51]  ❯ 

The file that sphinx mentions exists, and is an image. However, sphinx is doing path.join(app.srcdir, imgpath) which means it's actually looking for D:\Code\Fomu\foboot\hw\build\documentation\usb-icon.jpg which doesn't exist.

literalinclude no content permitted

First of all thank you for this amazing converter, I really like it so far. However, when I try to include an external cpp file in one of my markdown with the following literalinclude directive:

.. literalinclude:: ../ch2-hello_world/exercises/exercise-01/main.cpp
   :language: cpp
   :caption: helloworldextended.cpp

The code is not rendered and I get the following warning in the raw build output:

../ch2-hello_world/exercises/exercise-01/README.md:12: WARNING: Error in "literalinclude" directive:
no content permitted.

.. literalinclude:: ../ch2-hello_world/exercises/exercise-01/main.cpp

:language: cpp
:caption: helloworldextended.cpp

However, if I add text or just a single character after the above literalinclude everything works as expected. The code from the cpp file renders fine.

.. literalinclude:: ../ch2-hello_world/exercises/exercise-01/main.cpp
   :language: cpp
   :caption: helloworldextended.cpp


here is some text

Am I missing an option at the end of the literalinclude or why is text after it required to render the code properly?

Here is the result on read the docs running Sphinx v1.8.5, python 3.7 and m2r v0.2.1

broken in pypi

When I checked converted rst file, it had some errors. However I built wheel from setup.py, and it was passed.

rst checked: http://rst.ninjs.org

Here is MD file, and setup.py

• https://github.com/darkonhub/darkon/blob/master/README.md
• https://github.com/darkonhub/darkon/blob/master/setup.py

And my pypi link is here: https://pypi.python.org/pypi/darkon

test failures with pypi distfile

The pypi distfile of 0.1.9 has a number of test failures for me on NetBSD/python-3.6.2:

======================================================================
ERROR: test_dryrun (tests.test_cli.TestConvert)
----------------------------------------------------------------------
Traceback (most recent call last):
  File "/scratch/textproc/py-m2r/work/m2r-0.1.9/tests/test_cli.py", line 63, in test_dryrun
    with open(target_file) as f:
FileNotFoundError: [Errno 2] No such file or directory: '/scratch/textproc/py-m2r/work/m2r-0.1.9/tests/test.rst'

======================================================================
ERROR: test_dryrun (tests.test_cli.TestConvert)
----------------------------------------------------------------------
Traceback (most recent call last):
  File "/scratch/textproc/py-m2r/work/m2r-0.1.9/tests/test_cli.py", line 39, in tearDown
    f.write(self._orig_rst)
AttributeError: 'TestConvert' object has no attribute '_orig_rst'

======================================================================
ERROR: test_overwrite_file (tests.test_cli.TestConvert)
----------------------------------------------------------------------
Traceback (most recent call last):
  File "/scratch/textproc/py-m2r/work/m2r-0.1.9/tests/test_cli.py", line 89, in test_overwrite_file
    main()
  File "/scratch/textproc/py-m2r/work/m2r-0.1.9/m2r.py", line 572, in main
    output = parse_from_file(file)
  File "/scratch/textproc/py-m2r/work/m2r-0.1.9/m2r.py", line 547, in parse_from_file
    raise OSError('No such file exists: {}'.format(file))
OSError: No such file exists: /scratch/textproc/py-m2r/work/m2r-0.1.9/tests/test.md

======================================================================
ERROR: test_overwrite_option (tests.test_cli.TestConvert)
----------------------------------------------------------------------
Traceback (most recent call last):
  File "/scratch/textproc/py-m2r/work/m2r-0.1.9/tests/test_cli.py", line 105, in test_overwrite_option
    main()
  File "/scratch/textproc/py-m2r/work/m2r-0.1.9/m2r.py", line 572, in main
    output = parse_from_file(file)
  File "/scratch/textproc/py-m2r/work/m2r-0.1.9/m2r.py", line 547, in parse_from_file
    raise OSError('No such file exists: {}'.format(file))
OSError: No such file exists: /scratch/textproc/py-m2r/work/m2r-0.1.9/tests/test.md

======================================================================
ERROR: test_parse_file (tests.test_cli.TestConvert)
----------------------------------------------------------------------
Traceback (most recent call last):
  File "/scratch/textproc/py-m2r/work/m2r-0.1.9/tests/test_cli.py", line 55, in test_parse_file
    output = parse_from_file(test_md)
  File "/scratch/textproc/py-m2r/work/m2r-0.1.9/m2r.py", line 547, in parse_from_file
    raise OSError('No such file exists: {}'.format(file))
OSError: No such file exists: /scratch/textproc/py-m2r/work/m2r-0.1.9/tests/test.md

======================================================================
ERROR: test_underscore_option (tests.test_cli.TestConvert)
----------------------------------------------------------------------
Traceback (most recent call last):
  File "/scratch/textproc/py-m2r/work/m2r-0.1.9/tests/test_cli.py", line 117, in test_underscore_option
    main()
  File "/scratch/textproc/py-m2r/work/m2r-0.1.9/m2r.py", line 572, in main
    output = parse_from_file(file)
  File "/scratch/textproc/py-m2r/work/m2r-0.1.9/m2r.py", line 547, in parse_from_file
    raise OSError('No such file exists: {}'.format(file))
OSError: No such file exists: /scratch/textproc/py-m2r/work/m2r-0.1.9/tests/test.md

======================================================================
ERROR: test_write_file (tests.test_cli.TestConvert)
----------------------------------------------------------------------
Traceback (most recent call last):
  File "/scratch/textproc/py-m2r/work/m2r-0.1.9/tests/test_cli.py", line 77, in test_write_file
    main()
  File "/scratch/textproc/py-m2r/work/m2r-0.1.9/m2r.py", line 572, in main
    output = parse_from_file(file)
  File "/scratch/textproc/py-m2r/work/m2r-0.1.9/m2r.py", line 547, in parse_from_file
    raise OSError('No such file exists: {}'.format(file))
OSError: No such file exists: /scratch/textproc/py-m2r/work/m2r-0.1.9/tests/test.md

======================================================================
ERROR: test_dryrun (tests.test_cli.TestConvert)
----------------------------------------------------------------------
Traceback (most recent call last):
  File "/scratch/textproc/py-m2r/work/m2r-0.1.9/tests/test_cli.py", line 68, in test_dryrun
    main()
  File "/scratch/textproc/py-m2r/work/m2r-0.1.9/m2r.py", line 572, in main
    output = parse_from_file(file)
  File "/scratch/textproc/py-m2r/work/m2r-0.1.9/m2r.py", line 547, in parse_from_file
    raise OSError('No such file exists: {}'.format(file))
OSError: No such file exists: /scratch/textproc/py-m2r/work/m2r-0.1.9/tests/test.md

======================================================================
ERROR: test_overwrite_file (tests.test_cli.TestConvert)
----------------------------------------------------------------------
Traceback (most recent call last):
  File "/scratch/textproc/py-m2r/work/m2r-0.1.9/tests/test_cli.py", line 89, in test_overwrite_file
    main()
  File "/scratch/textproc/py-m2r/work/m2r-0.1.9/m2r.py", line 572, in main
    output = parse_from_file(file)
  File "/scratch/textproc/py-m2r/work/m2r-0.1.9/m2r.py", line 547, in parse_from_file
    raise OSError('No such file exists: {}'.format(file))
OSError: No such file exists: /scratch/textproc/py-m2r/work/m2r-0.1.9/tests/test.md

======================================================================
ERROR: test_overwrite_option (tests.test_cli.TestConvert)
----------------------------------------------------------------------
Traceback (most recent call last):
  File "/scratch/textproc/py-m2r/work/m2r-0.1.9/tests/test_cli.py", line 105, in test_overwrite_option
    main()
  File "/scratch/textproc/py-m2r/work/m2r-0.1.9/m2r.py", line 572, in main
    output = parse_from_file(file)
  File "/scratch/textproc/py-m2r/work/m2r-0.1.9/m2r.py", line 547, in parse_from_file
    raise OSError('No such file exists: {}'.format(file))
OSError: No such file exists: /scratch/textproc/py-m2r/work/m2r-0.1.9/tests/test.md

======================================================================
ERROR: test_parse_file (tests.test_cli.TestConvert)
----------------------------------------------------------------------
Traceback (most recent call last):
  File "/scratch/textproc/py-m2r/work/m2r-0.1.9/tests/test_cli.py", line 55, in test_parse_file
    output = parse_from_file(test_md)
  File "/scratch/textproc/py-m2r/work/m2r-0.1.9/m2r.py", line 547, in parse_from_file
    raise OSError('No such file exists: {}'.format(file))
OSError: No such file exists: /scratch/textproc/py-m2r/work/m2r-0.1.9/tests/test.md

======================================================================
ERROR: test_underscore_option (tests.test_cli.TestConvert)
----------------------------------------------------------------------
Traceback (most recent call last):
  File "/scratch/textproc/py-m2r/work/m2r-0.1.9/tests/test_cli.py", line 117, in test_underscore_option
    main()
  File "/scratch/textproc/py-m2r/work/m2r-0.1.9/m2r.py", line 572, in main
    output = parse_from_file(file)
  File "/scratch/textproc/py-m2r/work/m2r-0.1.9/m2r.py", line 547, in parse_from_file
    raise OSError('No such file exists: {}'.format(file))
OSError: No such file exists: /scratch/textproc/py-m2r/work/m2r-0.1.9/tests/test.md

======================================================================
ERROR: test_write_file (tests.test_cli.TestConvert)
----------------------------------------------------------------------
Traceback (most recent call last):
  File "/scratch/textproc/py-m2r/work/m2r-0.1.9/tests/test_cli.py", line 77, in test_write_file
    main()
  File "/scratch/textproc/py-m2r/work/m2r-0.1.9/m2r.py", line 572, in main
    output = parse_from_file(file)
  File "/scratch/textproc/py-m2r/work/m2r-0.1.9/m2r.py", line 547, in parse_from_file
    raise OSError('No such file exists: {}'.format(file))
OSError: No such file exists: /scratch/textproc/py-m2r/work/m2r-0.1.9/tests/test.md

======================================================================
FAIL: test_python_code_block (tests.test_renderer.TestCodeBlock)
----------------------------------------------------------------------
Traceback (most recent call last):
  File "/scratch/textproc/py-m2r/work/m2r-0.1.9/tests/test_renderer.py", line 303, in test_python_code_block
    out = self.conv(src)
  File "/scratch/textproc/py-m2r/work/m2r-0.1.9/tests/test_renderer.py", line 16, in conv
    self.check_rst(out)
  File "/scratch/textproc/py-m2r/work/m2r-0.1.9/tests/test_renderer.py", line 34, in check_rst
    self.assertLess(pub.document.reporter.max_level, 0)
AssertionError: 2 not less than 0

======================================================================
FAIL: test_python_code_block_indent (tests.test_renderer.TestCodeBlock)
----------------------------------------------------------------------
Traceback (most recent call last):
  File "/scratch/textproc/py-m2r/work/m2r-0.1.9/tests/test_renderer.py", line 313, in test_python_code_block_indent
    out = self.conv(src)
  File "/scratch/textproc/py-m2r/work/m2r-0.1.9/tests/test_renderer.py", line 16, in conv
    self.check_rst(out)
  File "/scratch/textproc/py-m2r/work/m2r-0.1.9/tests/test_renderer.py", line 34, in check_rst
    self.assertLess(pub.document.reporter.max_level, 0)
AssertionError: 2 not less than 0

======================================================================
FAIL: test_code (tests.test_renderer.TestConplexText)
----------------------------------------------------------------------
Traceback (most recent call last):
  File "/scratch/textproc/py-m2r/work/m2r-0.1.9/tests/test_renderer.py", line 590, in test_code
    self.conv(src)
  File "/scratch/textproc/py-m2r/work/m2r-0.1.9/tests/test_renderer.py", line 16, in conv
    self.check_rst(out)
  File "/scratch/textproc/py-m2r/work/m2r-0.1.9/tests/test_renderer.py", line 34, in check_rst
    self.assertLess(pub.document.reporter.max_level, 0)
AssertionError: 2 not less than 0

======================================================================
FAIL: test_python_code_block (tests.test_renderer.TestCodeBlock)
----------------------------------------------------------------------
Traceback (most recent call last):
  File "/scratch/textproc/py-m2r/work/m2r-0.1.9/tests/test_renderer.py", line 303, in test_python_code_block
    out = self.conv(src)
  File "/scratch/textproc/py-m2r/work/m2r-0.1.9/tests/test_renderer.py", line 16, in conv
    self.check_rst(out)
  File "/scratch/textproc/py-m2r/work/m2r-0.1.9/tests/test_renderer.py", line 34, in check_rst
    self.assertLess(pub.document.reporter.max_level, 0)
AssertionError: 2 not less than 0

======================================================================
FAIL: test_python_code_block_indent (tests.test_renderer.TestCodeBlock)
----------------------------------------------------------------------
Traceback (most recent call last):
  File "/scratch/textproc/py-m2r/work/m2r-0.1.9/tests/test_renderer.py", line 313, in test_python_code_block_indent
    out = self.conv(src)
  File "/scratch/textproc/py-m2r/work/m2r-0.1.9/tests/test_renderer.py", line 16, in conv
    self.check_rst(out)
  File "/scratch/textproc/py-m2r/work/m2r-0.1.9/tests/test_renderer.py", line 34, in check_rst
    self.assertLess(pub.document.reporter.max_level, 0)
AssertionError: 2 not less than 0

======================================================================
FAIL: test_code (tests.test_renderer.TestConplexText)
----------------------------------------------------------------------
Traceback (most recent call last):
  File "/scratch/textproc/py-m2r/work/m2r-0.1.9/tests/test_renderer.py", line 590, in test_code
    self.conv(src)
  File "/scratch/textproc/py-m2r/work/m2r-0.1.9/tests/test_renderer.py", line 16, in conv
    self.check_rst(out)
  File "/scratch/textproc/py-m2r/work/m2r-0.1.9/tests/test_renderer.py", line 34, in check_rst
    self.assertLess(pub.document.reporter.max_level, 0)
AssertionError: 2 not less than 0

----------------------------------------------------------------------
Ran 148 tests in 1.371s

FAILED (failures=6, errors=13, skipped=2)

Some of them seem to be because test.md is not included in the tarball.
I'm not sure about the other ones.

formatting multi-line text

I am wondering about formating multi-line text to be converted to homogenous text. I have a sample text from a readme which is broken down due to maximal line length but in the end, it should be shown as a single text block. For example, recommonmark does this job properly...

The file should use UTF-8 encoding and can be written using [reStructuredText][rst]
 or [markdown][md use] with the appropriate [key set][md use]. It will be used
 to generate the project webpage on PyPI and will be displayed as the project homepage
 on common code-hosting services, and should be written for that purpose.

flake8: F821 undefined name in docs/m2r.py

Caught by #6 Fixed in #5

https://travis-ci.org/miyakogi/m2r/jobs/253178479#L264

https://github.com/miyakogi/m2r/blob/master/m2r.py#L523

API compatibility issue with Sphinx 2.0

/usr/local/lib/python3.6/dist-packages/m2r.py:652: RemovedInSphinx30Warning: app.add_source_parser() does not support suffix argument. Use app.add_source_suffix() instead.
  app.add_source_parser('.md', M2RParser)

I think you're hitting a compatibility issue with the new major version of Sphinx. Is that possible?

Support for end-before and start-after options

... that are present in standard .. include directive.

issue with nicely rewriting md links

We have the following changelog which is generated using auto-changelog (npm package):
You can see it published here: https://github.com/hexonet/python-sdk/blob/master/HISTORY.md

### Changelog

All notable changes to this project will be documented in this file. Dates are displayed in UTC.

Generated by [`auto-changelog`](https://github.com/CookPete/auto-changelog).

#### [1.2.5](https://github.com/hexonet/python-sdk/compare/1.2.4...1.2.5)

> 9 July 2018

- fix six import path [`a9ec1a1`](https://github.com/hexonet/python-sdk/commit/a9ec1a1547637535220b33eb86a8172a53634879)
- updated changelog [`9e775a8`](https://github.com/hexonet/python-sdk/commit/9e775a850af227ecfd227b3b838f989daf63edff)

#### [1.2.4](https://github.com/hexonet/python-sdk/compare/1.2.3...1.2.4)

> 9 July 2018

- updated changelog [`c5601be`](https://github.com/hexonet/python-sdk/commit/c5601beb264c7b7e763e88e11aafcc93da310edd)
- fix six import paths [`e304262`](https://github.com/hexonet/python-sdk/commit/e3042628792eefce6168b93220308b138647c8f0)
- set version 1.2.4 [`655b886`](https://github.com/hexonet/python-sdk/commit/655b88658c9c0b1db1be39af8700eb900a19ec87)

#### [1.2.3](https://github.com/hexonet/python-sdk/compare/1.2.2...1.2.3)

> 9 July 2018

- import renaming [`bd7dc80`](https://github.com/hexonet/python-sdk/commit/bd7dc80c9decaccb480333aa4fe51db0c3722389)
- set version to 1.2.2 [`5642b54`](https://github.com/hexonet/python-sdk/commit/5642b54c25dd3410f699fb54e0f97a4ee1957109)

#### [1.2.2](https://github.com/hexonet/python-sdk/compare/1.2.1...1.2.2)

> 9 July 2018

- try import renaming [`d3fa6ae`](https://github.com/hexonet/python-sdk/commit/d3fa6ae84e8bc0c6ec941964445085b5ea3f3da6)

#### [1.2.1](https://github.com/hexonet/python-sdk/compare/1.2.0...1.2.1)

> 9 July 2018

- test renamed imports [`0999708`](https://github.com/hexonet/python-sdk/commit/09997081ddf7c65a6f25fa1827cfb07fd68f82c5)
- updated changelog [`eb5e6d4`](https://github.com/hexonet/python-sdk/commit/eb5e6d408f088b34172414ed9283fb0fc20e3df3)
- set version 1.2.1 [`2d98115`](https://github.com/hexonet/python-sdk/commit/2d9811500081c0940e3f340af9265b1c66f36893)

#### [1.2.0](https://github.com/hexonet/python-sdk/compare/1.1.0...1.2.0)

> 9 July 2018

- introduced six for py2 and py3 support [`fa7403a`](https://github.com/hexonet/python-sdk/commit/fa7403a9b18dc11b9cf8c74da603c12cee01477a)
- updated changelog [`a0f7e2f`](https://github.com/hexonet/python-sdk/commit/a0f7e2f3418d238f2d4884d786c0d62383d3d0c9)
- apiconnector version 1.2.0 [`85ec52f`](https://github.com/hexonet/python-sdk/commit/85ec52f18007de6a9d37889cd1b20711968749fa)

#### [1.1.0](https://github.com/hexonet/python-sdk/compare/1.0.0...1.1.0)

> 9 July 2018

- added pep8 scripts and code refactoring [`95e0199`](https://github.com/hexonet/python-sdk/commit/95e0199073c19f842778d133ceea8d11a7f64ded)
- added sdk documentation and generator script [`01fe1e0`](https://github.com/hexonet/python-sdk/commit/01fe1e0b858690ad95a3e611b9871067af3132be)
- added changelog and changelog generator script [`a4bd960`](https://github.com/hexonet/python-sdk/commit/a4bd9606e5590388fac9f96c5621a9e03fd125c6)
- update apiconnector version [`f1804eb`](https://github.com/hexonet/python-sdk/commit/f1804eb7bbb48c6e338f5b065dc935820ddcc595)

#### 1.0.0

> 9 July 2018

- initial PyPi package release [`eb2ac4c`](https://github.com/hexonet/python-sdk/commit/eb2ac4c6458a3620938e429878582e0b1ab93f00)
- ignore .vscode subfolder [`67430e3`](https://github.com/hexonet/python-sdk/commit/67430e3419237823839b2946c324a93d7d8de22c)
- added .gitignore [`946bc01`](https://github.com/hexonet/python-sdk/commit/946bc01b7c3505c28400aca50b9d9d4d4de33684)
- Add files via upload [`aa2bc4d`](https://github.com/hexonet/python-sdk/commit/aa2bc4d5f92720c22b7853371ade371e1f95b9dd)
- Create README.md [`400e58b`](https://github.com/hexonet/python-sdk/commit/400e58b5d2c0db4102ad207c65845a537d95aa93)
- fix encoding problem (JIRA: HM-22) + fix in properties() results [`5dc88d4`](https://github.com/hexonet/python-sdk/commit/5dc88d4a85f90a7154d0ccde4df33faff0874591)
- support for python2.5, use HTTP instead of HTTPS for the URL [`88cedbf`](https://github.com/hexonet/python-sdk/commit/88cedbf82075e19a957349dbc14b2836d99f2117)
- support for python > 3; also backward compatible [`2756429`](https://github.com/hexonet/python-sdk/commit/27564296dcd0e0a388ce45b0e77c467e6d927a31)
- Initial commit [`c89c917`](https://github.com/hexonet/python-sdk/commit/c89c917845cda5cef9e4f3a4fb5dc9d022e48006)

The generated HTML File using sphinx + m2r looks like this https://hexonet.github.io/python-sdk/docs/_build/html/changelog.html
The generated html code looks like this:

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <meta http-equiv="X-UA-Compatible" content="IE=Edge" />
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
  
  <!-- Licensed under the Apache 2.0 License -->
  <link rel="stylesheet" type="text/css" href="_static/fonts/open-sans/stylesheet.css" />
  <!-- Licensed under the SIL Open Font License -->
  <link rel="stylesheet" type="text/css" href="_static/fonts/source-serif-pro/source-serif-pro.css" />
  <link rel="stylesheet" type="text/css" href="_static/css/bootstrap.min.css" />
  <link rel="stylesheet" type="text/css" href="_static/css/bootstrap-theme.min.css" />
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  
    <title>Changelog &#8212; hexonet.apiconnector 1.2 documentation</title>
    <link rel="stylesheet" href="_static/guzzle.css" type="text/css" />
    <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
    <script type="text/javascript" id="documentation_options" data-url_root="./" src="_static/documentation_options.js"></script>
    <script type="text/javascript" src="_static/jquery.js"></script>
    <script type="text/javascript" src="_static/underscore.js"></script>
    <script type="text/javascript" src="_static/doctools.js"></script>
    <link rel="shortcut icon" href="_static/hexonet-favicon.ico"/>
    <link rel="index" title="Index" href="genindex.html" />
    <link rel="search" title="Search" href="search.html" />
    <link rel="next" title="License" href="license.html" />
    <link rel="prev" title="Upgrading to Newer Releases" href="upgrading.html" />
  
   

  </head><body>
    <div class="related" role="navigation" aria-label="related navigation">
      <h3>Navigation</h3>
      <ul>
        <li class="right" style="margin-right: 10px">
          <a href="genindex.html" title="General Index"
             accesskey="I">index</a></li>
        <li class="right" >
          <a href="py-modindex.html" title="Python Module Index"
             >modules</a> |</li>
        <li class="right" >
          <a href="license.html" title="License"
             accesskey="N">next</a> |</li>
        <li class="right" >
          <a href="upgrading.html" title="Upgrading to Newer Releases"
             accesskey="P">previous</a> |</li>
        <li class="nav-item nav-item-0"><a href="index.html">hexonet.apiconnector 1.2 documentation</a> &#187;</li> 
      </ul>
    </div>
    <div class="container-wrapper">

      <div id="mobile-toggle">
        <a href="#"><span class="glyphicon glyphicon-align-justify" aria-hidden="true"></span></a>
      </div>
  <div id="left-column">
    <div class="sphinxsidebar"><a href="
    index.html" class="text-logo">hexonet.apiconnector 1.2.6</a>
<div class="sidebar-block">
  <div class="sidebar-wrapper">
    <h2>Table Of Contents</h2>
  </div>
  <div class="sidebar-toc">
    
    
      <ul>
<li class="toctree-l1"><a class="reference internal" href="foreword.html">Foreword</a></li>
<li class="toctree-l1"><a class="reference internal" href="installation.html">Installation</a></li>
<li class="toctree-l1"><a class="reference internal" href="quickstart.html">Quickstart</a></li>
<li class="toctree-l1"><a class="reference internal" href="debugging.html">Debugging</a></li>
<li class="toctree-l1"><a class="reference internal" href="config.html">Configuration Handling</a></li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="api.html">SDK Documentation</a></li>
</ul>
<ul class="current">
<li class="toctree-l1"><a class="reference internal" href="upgrading.html">Upgrading to Newer Releases</a></li>
<li class="toctree-l1 current"><a class="current reference internal" href="#">Changelog</a><ul>
<li class="toctree-l2"><a class="reference internal" href="#id1">Changelog</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="license.html">License</a></li>
<li class="toctree-l1"><a class="reference internal" href="license.html#hexonet-developers">HEXONET Developers</a></li>
<li class="toctree-l1"><a class="reference internal" href="contributing.html">Contributing</a></li>
<li class="toctree-l1"><a class="reference internal" href="contributing.html#id2">Contributing</a></li>
<li class="toctree-l1"><a class="reference internal" href="contactus.html">Contact Us</a></li>
</ul>

    
  </div>
</div>
<div class="sidebar-block">
  <div class="sidebar-wrapper">
    <h2>Contents</h2>
    <div class="sidebar-localtoc">
      <ul>
<li><a class="reference internal" href="#">Changelog</a><ul>
<li><a class="reference internal" href="#id1">Changelog</a><ul>
<li><a class="reference internal" href="#id3">1.2.5</a></li>
<li><a class="reference internal" href="#id5">1.2.4</a></li>
<li><a class="reference internal" href="#id7">1.2.3</a></li>
<li><a class="reference internal" href="#id9">1.2.2</a></li>
<li><a class="reference internal" href="#id11">1.2.1</a></li>
<li><a class="reference internal" href="#id13">1.2.0</a></li>
<li><a class="reference internal" href="#id15">1.1.0</a></li>
<li><a class="reference internal" href="#id16">1.0.0</a></li>
</ul>
</li>
</ul>
</li>
</ul>

    </div>
  </div>
</div>
<div class="sidebar-block">
  <div class="sidebar-wrapper">
    <div id="main-search">
      <form class="form-inline" action="search.html" method="GET" role="form">
        <div class="input-group">
          <input name="q" type="text" class="form-control" placeholder="Search...">
        </div>
        <input type="hidden" name="check_keywords" value="yes" />
        <input type="hidden" name="area" value="default" />
      </form>
    </div>
  </div>
</div>
      
    </div>
  </div>
        <div id="right-column">
          
          <div role="navigation" aria-label="breadcrumbs navigation">
            <ol class="breadcrumb">
              <li><a href="index.html">Docs</a></li>
              
              <li>Changelog</li>
            </ol>
          </div>
          
          <div class="document clearer body">
            
  <div class="section" id="changelog">
<h1>Changelog<a class="headerlink" href="#changelog" title="Permalink to this headline">¶</a></h1>
<div class="section" id="id1">
<h2>Changelog<a class="headerlink" href="#id1" title="Permalink to this headline">¶</a></h2>
<p>All notable changes to this project will be documented in this file. Dates are displayed in UTC.</p>
<p>Generated by <cite>``auto-changelog`</cite> &lt;<a class="reference external" href="https://github.com/CookPete/auto-changelog">https://github.com/CookPete/auto-changelog</a>&gt;`_.</p>
<div class="section" id="id3">
<h3><a class="reference external" href="https://github.com/hexonet/python-sdk/compare/1.2.4...1.2.5">1.2.5</a><a class="headerlink" href="#id3" title="Permalink to this headline">¶</a></h3>
<blockquote>
<div>9 July 2018</div></blockquote>
<ul class="simple">
<li>fix six import path <cite>``a9ec1a1`</cite> &lt;<a class="reference external" href="https://github.com/hexonet/python-sdk/commit/a9ec1a1547637535220b33eb86a8172a53634879">https://github.com/hexonet/python-sdk/commit/a9ec1a1547637535220b33eb86a8172a53634879</a>&gt;`_</li>
<li>updated changelog <cite>``9e775a8`</cite> &lt;<a class="reference external" href="https://github.com/hexonet/python-sdk/commit/9e775a850af227ecfd227b3b838f989daf63edff">https://github.com/hexonet/python-sdk/commit/9e775a850af227ecfd227b3b838f989daf63edff</a>&gt;`_</li>
</ul>
</div>
<div class="section" id="id5">
<h3><a class="reference external" href="https://github.com/hexonet/python-sdk/compare/1.2.3...1.2.4">1.2.4</a><a class="headerlink" href="#id5" title="Permalink to this headline">¶</a></h3>
<blockquote>
<div>9 July 2018</div></blockquote>
<ul class="simple">
<li>updated changelog <cite>``c5601be`</cite> &lt;<a class="reference external" href="https://github.com/hexonet/python-sdk/commit/c5601beb264c7b7e763e88e11aafcc93da310edd">https://github.com/hexonet/python-sdk/commit/c5601beb264c7b7e763e88e11aafcc93da310edd</a>&gt;`_</li>
<li>fix six import paths <cite>``e304262`</cite> &lt;<a class="reference external" href="https://github.com/hexonet/python-sdk/commit/e3042628792eefce6168b93220308b138647c8f0">https://github.com/hexonet/python-sdk/commit/e3042628792eefce6168b93220308b138647c8f0</a>&gt;`_</li>
<li>set version 1.2.4 <cite>``655b886`</cite> &lt;<a class="reference external" href="https://github.com/hexonet/python-sdk/commit/655b88658c9c0b1db1be39af8700eb900a19ec87">https://github.com/hexonet/python-sdk/commit/655b88658c9c0b1db1be39af8700eb900a19ec87</a>&gt;`_</li>
</ul>
</div>
<div class="section" id="id7">
<h3><a class="reference external" href="https://github.com/hexonet/python-sdk/compare/1.2.2...1.2.3">1.2.3</a><a class="headerlink" href="#id7" title="Permalink to this headline">¶</a></h3>
<blockquote>
<div>9 July 2018</div></blockquote>
<ul class="simple">
<li>import renaming <cite>``bd7dc80`</cite> &lt;<a class="reference external" href="https://github.com/hexonet/python-sdk/commit/bd7dc80c9decaccb480333aa4fe51db0c3722389">https://github.com/hexonet/python-sdk/commit/bd7dc80c9decaccb480333aa4fe51db0c3722389</a>&gt;`_</li>
<li>set version to 1.2.2 <cite>``5642b54`</cite> &lt;<a class="reference external" href="https://github.com/hexonet/python-sdk/commit/5642b54c25dd3410f699fb54e0f97a4ee1957109">https://github.com/hexonet/python-sdk/commit/5642b54c25dd3410f699fb54e0f97a4ee1957109</a>&gt;`_</li>
</ul>
</div>
<div class="section" id="id9">
<h3><a class="reference external" href="https://github.com/hexonet/python-sdk/compare/1.2.1...1.2.2">1.2.2</a><a class="headerlink" href="#id9" title="Permalink to this headline">¶</a></h3>
<blockquote>
<div>9 July 2018</div></blockquote>
<ul class="simple">
<li>try import renaming <cite>``d3fa6ae`</cite> &lt;<a class="reference external" href="https://github.com/hexonet/python-sdk/commit/d3fa6ae84e8bc0c6ec941964445085b5ea3f3da6">https://github.com/hexonet/python-sdk/commit/d3fa6ae84e8bc0c6ec941964445085b5ea3f3da6</a>&gt;`_</li>
</ul>
</div>
<div class="section" id="id11">
<h3><a class="reference external" href="https://github.com/hexonet/python-sdk/compare/1.2.0...1.2.1">1.2.1</a><a class="headerlink" href="#id11" title="Permalink to this headline">¶</a></h3>
<blockquote>
<div>9 July 2018</div></blockquote>
<ul class="simple">
<li>test renamed imports <cite>``0999708`</cite> &lt;<a class="reference external" href="https://github.com/hexonet/python-sdk/commit/09997081ddf7c65a6f25fa1827cfb07fd68f82c5">https://github.com/hexonet/python-sdk/commit/09997081ddf7c65a6f25fa1827cfb07fd68f82c5</a>&gt;`_</li>
<li>updated changelog <cite>``eb5e6d4`</cite> &lt;<a class="reference external" href="https://github.com/hexonet/python-sdk/commit/eb5e6d408f088b34172414ed9283fb0fc20e3df3">https://github.com/hexonet/python-sdk/commit/eb5e6d408f088b34172414ed9283fb0fc20e3df3</a>&gt;`_</li>
<li>set version 1.2.1 <cite>``2d98115`</cite> &lt;<a class="reference external" href="https://github.com/hexonet/python-sdk/commit/2d9811500081c0940e3f340af9265b1c66f36893">https://github.com/hexonet/python-sdk/commit/2d9811500081c0940e3f340af9265b1c66f36893</a>&gt;`_</li>
</ul>
</div>
<div class="section" id="id13">
<h3><a class="reference external" href="https://github.com/hexonet/python-sdk/compare/1.1.0...1.2.0">1.2.0</a><a class="headerlink" href="#id13" title="Permalink to this headline">¶</a></h3>
<blockquote>
<div>9 July 2018</div></blockquote>
<ul class="simple">
<li>introduced six for py2 and py3 support <cite>``fa7403a`</cite> &lt;<a class="reference external" href="https://github.com/hexonet/python-sdk/commit/fa7403a9b18dc11b9cf8c74da603c12cee01477a">https://github.com/hexonet/python-sdk/commit/fa7403a9b18dc11b9cf8c74da603c12cee01477a</a>&gt;`_</li>
<li>updated changelog <cite>``a0f7e2f`</cite> &lt;<a class="reference external" href="https://github.com/hexonet/python-sdk/commit/a0f7e2f3418d238f2d4884d786c0d62383d3d0c9">https://github.com/hexonet/python-sdk/commit/a0f7e2f3418d238f2d4884d786c0d62383d3d0c9</a>&gt;`_</li>
<li>apiconnector version 1.2.0 <cite>``85ec52f`</cite> &lt;<a class="reference external" href="https://github.com/hexonet/python-sdk/commit/85ec52f18007de6a9d37889cd1b20711968749fa">https://github.com/hexonet/python-sdk/commit/85ec52f18007de6a9d37889cd1b20711968749fa</a>&gt;`_</li>
</ul>
</div>
<div class="section" id="id15">
<h3><a class="reference external" href="https://github.com/hexonet/python-sdk/compare/1.0.0...1.1.0">1.1.0</a><a class="headerlink" href="#id15" title="Permalink to this headline">¶</a></h3>
<blockquote>
<div>9 July 2018</div></blockquote>
<ul class="simple">
<li>added pep8 scripts and code refactoring <cite>``95e0199`</cite> &lt;<a class="reference external" href="https://github.com/hexonet/python-sdk/commit/95e0199073c19f842778d133ceea8d11a7f64ded">https://github.com/hexonet/python-sdk/commit/95e0199073c19f842778d133ceea8d11a7f64ded</a>&gt;`_</li>
<li>added sdk documentation and generator script <cite>``01fe1e0`</cite> &lt;<a class="reference external" href="https://github.com/hexonet/python-sdk/commit/01fe1e0b858690ad95a3e611b9871067af3132be">https://github.com/hexonet/python-sdk/commit/01fe1e0b858690ad95a3e611b9871067af3132be</a>&gt;`_</li>
<li>added changelog and changelog generator script <cite>``a4bd960`</cite> &lt;<a class="reference external" href="https://github.com/hexonet/python-sdk/commit/a4bd9606e5590388fac9f96c5621a9e03fd125c6">https://github.com/hexonet/python-sdk/commit/a4bd9606e5590388fac9f96c5621a9e03fd125c6</a>&gt;`_</li>
<li>update apiconnector version <cite>``f1804eb`</cite> &lt;<a class="reference external" href="https://github.com/hexonet/python-sdk/commit/f1804eb7bbb48c6e338f5b065dc935820ddcc595">https://github.com/hexonet/python-sdk/commit/f1804eb7bbb48c6e338f5b065dc935820ddcc595</a>&gt;`_</li>
</ul>
</div>
<div class="section" id="id16">
<h3>1.0.0<a class="headerlink" href="#id16" title="Permalink to this headline">¶</a></h3>
<blockquote>
<div>9 July 2018</div></blockquote>
<ul class="simple">
<li>initial PyPi package release <cite>``eb2ac4c`</cite> &lt;<a class="reference external" href="https://github.com/hexonet/python-sdk/commit/eb2ac4c6458a3620938e429878582e0b1ab93f00">https://github.com/hexonet/python-sdk/commit/eb2ac4c6458a3620938e429878582e0b1ab93f00</a>&gt;`_</li>
<li>ignore .vscode subfolder <cite>``67430e3`</cite> &lt;<a class="reference external" href="https://github.com/hexonet/python-sdk/commit/67430e3419237823839b2946c324a93d7d8de22c">https://github.com/hexonet/python-sdk/commit/67430e3419237823839b2946c324a93d7d8de22c</a>&gt;`_</li>
<li>added .gitignore <cite>``946bc01`</cite> &lt;<a class="reference external" href="https://github.com/hexonet/python-sdk/commit/946bc01b7c3505c28400aca50b9d9d4d4de33684">https://github.com/hexonet/python-sdk/commit/946bc01b7c3505c28400aca50b9d9d4d4de33684</a>&gt;`_</li>
<li>Add files via upload <cite>``aa2bc4d`</cite> &lt;<a class="reference external" href="https://github.com/hexonet/python-sdk/commit/aa2bc4d5f92720c22b7853371ade371e1f95b9dd">https://github.com/hexonet/python-sdk/commit/aa2bc4d5f92720c22b7853371ade371e1f95b9dd</a>&gt;`_</li>
<li>Create README.md <cite>``400e58b`</cite> &lt;<a class="reference external" href="https://github.com/hexonet/python-sdk/commit/400e58b5d2c0db4102ad207c65845a537d95aa93">https://github.com/hexonet/python-sdk/commit/400e58b5d2c0db4102ad207c65845a537d95aa93</a>&gt;`_</li>
<li>fix encoding problem (JIRA: HM-22) + fix in properties() results <cite>``5dc88d4`</cite> &lt;<a class="reference external" href="https://github.com/hexonet/python-sdk/commit/5dc88d4a85f90a7154d0ccde4df33faff0874591">https://github.com/hexonet/python-sdk/commit/5dc88d4a85f90a7154d0ccde4df33faff0874591</a>&gt;`_</li>
<li>support for python2.5, use HTTP instead of HTTPS for the URL <cite>``88cedbf`</cite> &lt;<a class="reference external" href="https://github.com/hexonet/python-sdk/commit/88cedbf82075e19a957349dbc14b2836d99f2117">https://github.com/hexonet/python-sdk/commit/88cedbf82075e19a957349dbc14b2836d99f2117</a>&gt;`_</li>
<li>support for python &gt; 3; also backward compatible <cite>``2756429`</cite> &lt;<a class="reference external" href="https://github.com/hexonet/python-sdk/commit/27564296dcd0e0a388ce45b0e77c467e6d927a31">https://github.com/hexonet/python-sdk/commit/27564296dcd0e0a388ce45b0e77c467e6d927a31</a>&gt;`_</li>
<li>Initial commit <cite>``c89c917`</cite> &lt;<a class="reference external" href="https://github.com/hexonet/python-sdk/commit/c89c917845cda5cef9e4f3a4fb5dc9d022e48006">https://github.com/hexonet/python-sdk/commit/c89c917845cda5cef9e4f3a4fb5dc9d022e48006</a>&gt;`_</li>
</ul>
</div>
</div>
</div>


          </div>
            
  <div class="footer-relations">
    
      <div class="pull-left">
        <a class="btn btn-default" href="upgrading.html" title="previous chapter (use the left arrow)">Upgrading to Newer Releases</a>
      </div>
    
      <div class="pull-right">
        <a class="btn btn-default" href="license.html" title="next chapter (use the right arrow)">License</a>
      </div>
    </div>
    <div class="clearer"></div>
  
        </div>
        <div class="clearfix"></div>
    </div>
    <div class="related" role="navigation" aria-label="related navigation">
      <h3>Navigation</h3>
      <ul>
        <li class="right" style="margin-right: 10px">
          <a href="genindex.html" title="General Index"
             >index</a></li>
        <li class="right" >
          <a href="py-modindex.html" title="Python Module Index"
             >modules</a> |</li>
        <li class="right" >
          <a href="license.html" title="License"
             >next</a> |</li>
        <li class="right" >
          <a href="upgrading.html" title="Upgrading to Newer Releases"
             >previous</a> |</li>
        <li class="nav-item nav-item-0"><a href="index.html">hexonet.apiconnector 1.2 documentation</a> &#187;</li> 
      </ul>
    </div>
<script type="text/javascript">
  $("#mobile-toggle a").click(function () {
    $("#left-column").toggle();
  });
</script>
<script type="text/javascript" src="_static/js/bootstrap.js"></script>
  <div class="footer">
    &copy; Copyright 2018 by HEXONET GmbH. Created using <a href="http://sphinx.pocoo.org/">Sphinx</a>.
  </div>
  </body>
</html>

Can the link generator be improved so that the visual output fits more to the .md one?

mdinclude not using correct header names if numbers are used

Hi, I've noticed an issue with ids for headers when using .. mdinclude:: file.md if the header contains a number.

For example, within file.md I have the header: #### March 2020. I'd expect the id for this to be march-2020, however, when displaying this file within a .rst using mdinclude, the id becomes id1 if a number is used.

#### March Twenty Twenty has the id march-twenty-twenty like you'd expect, but I'd prefer to use numbers.

Is this a known issue or am I doing something wrong? Thanks

Sphinx documentation with m2r has missing links to sections in the same markdown file

I have a simple markdown such as

# My Test

- [My Test](#my-test)

When I run m2r directly on this markdown file I get the rst output as expected. However when using m2r via sphinx extension the generated HTML document doesn't have the link generated correctly. My Sphinx conf.py file has m2r_parse_relative_links = True set to true to follow relative links.

Directives such as `toctree` render incorrectly due to an extra newline during conversion

I've run into an issue with Sphinx directives (toctree specifically) mixed into Markdown files. The directive itself works correctly, but maxdepth doesn't work. This appears to be because of an empty line between the directive itself and the maxdepth line, after conversion to .rst.

Looking at the m2r source (and testing a patch on my local copy), it looks like it's specifically a trailing newline in a directive method (line 510 of m2r.py). The fix looks simple, so I'll open a pull request for that.

For reproduction of the issue, take the following .md file:

# Header goes here

.. toctree::
   :maxdepth: 2
   :caption: In This Section:

   deploy_local_dev.md
   deploy_rhel7_centos7.md
   deploy_ubuntu.md

This converts to the following .rst source (tested with m2r --dry-run):

Header goes here
================

.. toctree::

   :maxdepth: 2
   :caption: In This Section:

   deploy_local_dev.md
   deploy_rhel7_centos7.md
   deploy_ubuntu.md

The extra newline between the toctree directive and the :maxdepth: 2 line results in maxdepth being ignored, and also results in a warning being issued by Sphinx (WARNING: toctree contains reference to nonexisting document ':maxdepth: 2').

Relatively linking to documents

Does m2r support markdown links to other documents, when using sphinx? With recommonmark, if you link to an md doc, it'll parse that and make a link to the related html doc. It seems with m2r that it's just making relative html links, with the exact contents of the link. I'm trying to keep some compatibility between github docs and sphinx generated docs, so would like to be able to use relative links to the .md files, like in recommonmark.

Is this possible in m2r?

Release new version?

In order to use Sphinx 3 with m2r, I have to add the github URL to my requirements file, which is a dirty feeling. Can we get a new release of m2r that officially supports modern Sphinx installs? Cheers

Edit: I created sphinx-mdinclude as a modernized, Sphinx-centered fork of m2r/m2r2:

https://sphinx-mdinclude.readthedocs.io/en/latest/

Link Syntax and Teletype Syntax do not go well together

I have no problems to write this Commonmark / Markdown:

1. [`LibraryTestCase`](../tests/LibraryTestCase.php)

It renders perfectly as Markdown:

1. LibraryTestCase

Unless I use it with m2r in a Sphinx build, m2r just does not get it to make the links text teletype:

InputError using include and mdinclude

When using a chain of includes, every single one of them needs to be mdinclude if the ultimate target is a Markdown file. This stumped me for a while and I am reporting this for future readers.

$ make html
Running Sphinx v1.8.0
making output directory...
building [mo]: targets for 0 po files that are out of date
building [html]: targets for 11 source files that are out of date
updating environment: 11 added, 0 changed, 0 removed
reading sources... [100%] usage
readme.rst <included from /Users/micahsmith/workspace/aa/docs/index.rst>:1: WARNING: Problems with "mdinclude" directive path:                                                                               
InputError: [Errno 2] No such file or directory: 'readme.rst <included from /Users/micahsmith/workspace/aa/README.md'. 

The error message suggests that there are some problems with paths, and I spent a lot of time thinking I had a problem with relative paths or something crazy. Perhaps the error message can be improved.

I had the following structure

$ tree '*index.rst|*readme*|*README*' --prune
.
├── README.md
└── docs
    ├── index.rst
    └── readme.rst

$ cat docs/index.rst
.. include:: readme.rst

$ cat docs/readme.rst 
.. mdinclude:: ../README.md

The solution is to change include to mdinclude in docs/index.rst.

Anchor a tags self reference being filtered

Anchor links, when the Markdown has references to it's own Headers, that result in HTML a tag links in the rendered file don't work. Currently if I have a

thispage.md

# headerk
content
# headerj
a [link to header k](thispage#headerk)

This works correctly inside github but the destination after the # get's filtered and disappears, resulting in a link to self.

We are having an issue with this here.

CHANGES.md not included in pypi distfile

Please include CHANGES.md into the pypi distfile; it makes life easier for packagers.

Static file in markdown

Hi all, I have a link to an image in my README.md file.

presentation:<img src="docs/source/.static/i.png">

When the mdinclude directive parses this, it keeps the original URL for the image, but sphinx moves everything to a docs/build/_static/ directory. Is there anyway to update this url?

Suggestion: want to hide CLI options

I'm making a CLI tool that uses m2r.
It depends on m2r just internally, and I don't want to expose m2r's CLI options on my tool.

The current m2r automatically exposes its CLI options when imported because m2r.py configures ArgumentParser on the top level.

I think it would be better if the user can choose whether or not to expose m2r's options.

Nine tests fails with Python 3.6 but succeed with 3.7 (or is it something about the version of Sphinx)

When running packaging scripts for openSUSE Tumbleweed (with python3-3.7.3 and python3-Sphinx-2.2.2) the test suite passes without any problem, but when I built it for the bit older stable Leap 15.1 distribution (python3-3.6.5 and python3-Sphinx-2.2.2) I get nine tests failing:

[   32s] =================================== FAILURES ===================================
[   32s] _________________ TestConvert.test_anonymous_reference_option __________________
[   32s] 
[   32s] self = <tests.test_cli.TestConvert testMethod=test_anonymous_reference_option>
[   32s] 
[   32s]     def setUp(self):
[   32s]         # reset cli options
[   32s]         options.overwrite = False
[   32s]         options.dry_run = False
[   32s]         options.no_underscore_emphasis = False
[   32s]         options.anonymous_references = False
[   32s]         options.disable_inline_math = False
[   32s]         self._orig_argv = copy(sys.argv)
[   32s]         if path.exists(test_rst):
[   32s]             with open(test_rst) as f:
[   32s] >               self._orig_rst = f.read()
[   32s] 
[   32s] tests/test_cli.py:41: 
[   32s] _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ 
[   32s] 
[   32s] self = <encodings.ascii.IncrementalDecoder object at 0x7f2d78cd8828>
[   32s] input = b'\nTitle\n=====\n\nSubTitle\n--------\n\n**content**\n\n\xe3\x82\xb5\xe3\x83\x96\xe3\x82\xbf\xe3\x82\xa4\xe3\x83\x88\xe3\x83\xab\n------------\n\n`A link to GitHub <http://github.com/>`_\n\nThis is :math:`E = mc^2` inline math.\n'
[   32s] final = True
[   32s] 
[   32s]     def decode(self, input, final=False):
[   32s] >       return codecs.ascii_decode(input, self.errors)[0]
[   32s] E       UnicodeDecodeError: 'ascii' codec can't decode byte 0xe3 in position 46: ordinal not in range(128)
[   32s] 
[   32s] /usr/lib64/python3.6/encodings/ascii.py:26: UnicodeDecodeError
[   32s] _____________________ TestConvert.test_disable_inline_math _____________________
[   32s] 
[   32s] self = <tests.test_cli.TestConvert testMethod=test_disable_inline_math>
[   32s] 
[   32s]     def setUp(self):
[   32s]         # reset cli options
[   32s]         options.overwrite = False
[   32s]         options.dry_run = False
[   32s]         options.no_underscore_emphasis = False
[   32s]         options.anonymous_references = False
[   32s]         options.disable_inline_math = False
[   32s]         self._orig_argv = copy(sys.argv)
[   32s]         if path.exists(test_rst):
[   32s]             with open(test_rst) as f:
[   32s] >               self._orig_rst = f.read()
[   32s] 
[   32s] tests/test_cli.py:41: 
[   32s] _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ 
[   32s] 
[   32s] self = <encodings.ascii.IncrementalDecoder object at 0x7f2d78cd8a58>
[   32s] input = b'\nTitle\n=====\n\nSubTitle\n--------\n\n**content**\n\n\xe3\x82\xb5\xe3\x83\x96\xe3\x82\xbf\xe3\x82\xa4\xe3\x83\x88\xe3\x83\xab\n------------\n\n`A link to GitHub <http://github.com/>`_\n\nThis is :math:`E = mc^2` inline math.\n'
[   32s] final = True
[   32s] 
[   32s]     def decode(self, input, final=False):
[   32s] >       return codecs.ascii_decode(input, self.errors)[0]
[   32s] E       UnicodeDecodeError: 'ascii' codec can't decode byte 0xe3 in position 46: ordinal not in range(128)
[   32s] 
[   32s] /usr/lib64/python3.6/encodings/ascii.py:26: UnicodeDecodeError
[   32s] ___________________________ TestConvert.test_dryrun ____________________________
[   32s] 
[   32s] self = <tests.test_cli.TestConvert testMethod=test_dryrun>
[   32s] 
[   32s]     def setUp(self):
[   32s]         # reset cli options
[   32s]         options.overwrite = False
[   32s]         options.dry_run = False
[   32s]         options.no_underscore_emphasis = False
[   32s]         options.anonymous_references = False
[   32s]         options.disable_inline_math = False
[   32s]         self._orig_argv = copy(sys.argv)
[   32s]         if path.exists(test_rst):
[   32s]             with open(test_rst) as f:
[   32s] >               self._orig_rst = f.read()
[   32s] 
[   32s] tests/test_cli.py:41: 
[   32s] _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ 
[   32s] 
[   32s] self = <encodings.ascii.IncrementalDecoder object at 0x7f2d78db7518>
[   32s] input = b'\nTitle\n=====\n\nSubTitle\n--------\n\n**content**\n\n\xe3\x82\xb5\xe3\x83\x96\xe3\x82\xbf\xe3\x82\xa4\xe3\x83\x88\xe3\x83\xab\n------------\n\n`A link to GitHub <http://github.com/>`_\n\nThis is :math:`E = mc^2` inline math.\n'
[   32s] final = True
[   32s] 
[   32s]     def decode(self, input, final=False):
[   32s] >       return codecs.ascii_decode(input, self.errors)[0]
[   32s] E       UnicodeDecodeError: 'ascii' codec can't decode byte 0xe3 in position 46: ordinal not in range(128)
[   32s] 
[   32s] /usr/lib64/python3.6/encodings/ascii.py:26: UnicodeDecodeError
[   32s] ___________________________ TestConvert.test_no_file ___________________________
[   32s] 
[   32s] self = <tests.test_cli.TestConvert testMethod=test_no_file>
[   32s] 
[   32s]     def setUp(self):
[   32s]         # reset cli options
[   32s]         options.overwrite = False
[   32s]         options.dry_run = False
[   32s]         options.no_underscore_emphasis = False
[   32s]         options.anonymous_references = False
[   32s]         options.disable_inline_math = False
[   32s]         self._orig_argv = copy(sys.argv)
[   32s]         if path.exists(test_rst):
[   32s]             with open(test_rst) as f:
[   32s] >               self._orig_rst = f.read()
[   32s] 
[   32s] tests/test_cli.py:41: 
[   32s] _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ 
[   32s] 
[   32s] self = <encodings.ascii.IncrementalDecoder object at 0x7f2d78dae668>
[   32s] input = b'\nTitle\n=====\n\nSubTitle\n--------\n\n**content**\n\n\xe3\x82\xb5\xe3\x83\x96\xe3\x82\xbf\xe3\x82\xa4\xe3\x83\x88\xe3\x83\xab\n------------\n\n`A link to GitHub <http://github.com/>`_\n\nThis is :math:`E = mc^2` inline math.\n'
[   32s] final = True
[   32s] 
[   32s]     def decode(self, input, final=False):
[   32s] >       return codecs.ascii_decode(input, self.errors)[0]
[   32s] E       UnicodeDecodeError: 'ascii' codec can't decode byte 0xe3 in position 46: ordinal not in range(128)
[   32s] 
[   32s] /usr/lib64/python3.6/encodings/ascii.py:26: UnicodeDecodeError
[   32s] _______________________ TestConvert.test_overwrite_file ________________________
[   32s] 
[   32s] self = <tests.test_cli.TestConvert testMethod=test_overwrite_file>
[   32s] 
[   32s]     def setUp(self):
[   32s]         # reset cli options
[   32s]         options.overwrite = False
[   32s]         options.dry_run = False
[   32s]         options.no_underscore_emphasis = False
[   32s]         options.anonymous_references = False
[   32s]         options.disable_inline_math = False
[   32s]         self._orig_argv = copy(sys.argv)
[   32s]         if path.exists(test_rst):
[   32s]             with open(test_rst) as f:
[   32s] >               self._orig_rst = f.read()
[   32s] 
[   32s] tests/test_cli.py:41: 
[   32s] _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ 
[   32s] 
[   32s] self = <encodings.ascii.IncrementalDecoder object at 0x7f2d78cd8780>
[   32s] input = b'\nTitle\n=====\n\nSubTitle\n--------\n\n**content**\n\n\xe3\x82\xb5\xe3\x83\x96\xe3\x82\xbf\xe3\x82\xa4\xe3\x83\x88\xe3\x83\xab\n------------\n\n`A link to GitHub <http://github.com/>`_\n\nThis is :math:`E = mc^2` inline math.\n'
[   32s] final = True
[   32s] 
[   32s]     def decode(self, input, final=False):
[   32s] >       return codecs.ascii_decode(input, self.errors)[0]
[   32s] E       UnicodeDecodeError: 'ascii' codec can't decode byte 0xe3 in position 46: ordinal not in range(128)
[   32s] 
[   32s] /usr/lib64/python3.6/encodings/ascii.py:26: UnicodeDecodeError
[   32s] ______________________ TestConvert.test_overwrite_option _______________________
[   32s] 
[   32s] self = <tests.test_cli.TestConvert testMethod=test_overwrite_option>
[   32s] 
[   32s]     def setUp(self):
[   32s]         # reset cli options
[   32s]         options.overwrite = False
[   32s]         options.dry_run = False
[   32s]         options.no_underscore_emphasis = False
[   32s]         options.anonymous_references = False
[   32s]         options.disable_inline_math = False
[   32s]         self._orig_argv = copy(sys.argv)
[   32s]         if path.exists(test_rst):
[   32s]             with open(test_rst) as f:
[   32s] >               self._orig_rst = f.read()
[   32s] 
[   32s] tests/test_cli.py:41: 
[   32s] _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ 
[   32s] 
[   32s] self = <encodings.ascii.IncrementalDecoder object at 0x7f2d78d92f28>
[   32s] input = b'\nTitle\n=====\n\nSubTitle\n--------\n\n**content**\n\n\xe3\x82\xb5\xe3\x83\x96\xe3\x82\xbf\xe3\x82\xa4\xe3\x83\x88\xe3\x83\xab\n------------\n\n`A link to GitHub <http://github.com/>`_\n\nThis is :math:`E = mc^2` inline math.\n'
[   32s] final = True
[   32s] 
[   32s]     def decode(self, input, final=False):
[   32s] >       return codecs.ascii_decode(input, self.errors)[0]
[   32s] E       UnicodeDecodeError: 'ascii' codec can't decode byte 0xe3 in position 46: ordinal not in range(128)
[   32s] 
[   32s] /usr/lib64/python3.6/encodings/ascii.py:26: UnicodeDecodeError
[   32s] _________________________ TestConvert.test_parse_file __________________________
[   32s] 
[   32s] self = <tests.test_cli.TestConvert testMethod=test_parse_file>
[   32s] 
[   32s]     def setUp(self):
[   32s]         # reset cli options
[   32s]         options.overwrite = False
[   32s]         options.dry_run = False
[   32s]         options.no_underscore_emphasis = False
[   32s]         options.anonymous_references = False
[   32s]         options.disable_inline_math = False
[   32s]         self._orig_argv = copy(sys.argv)
[   32s]         if path.exists(test_rst):
[   32s]             with open(test_rst) as f:
[   32s] >               self._orig_rst = f.read()
[   32s] 
[   32s] tests/test_cli.py:41: 
[   32s] _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ 
[   32s] 
[   32s] self = <encodings.ascii.IncrementalDecoder object at 0x7f2d78dbb278>
[   32s] input = b'\nTitle\n=====\n\nSubTitle\n--------\n\n**content**\n\n\xe3\x82\xb5\xe3\x83\x96\xe3\x82\xbf\xe3\x82\xa4\xe3\x83\x88\xe3\x83\xab\n------------\n\n`A link to GitHub <http://github.com/>`_\n\nThis is :math:`E = mc^2` inline math.\n'
[   32s] final = True
[   32s] 
[   32s]     def decode(self, input, final=False):
[   32s] >       return codecs.ascii_decode(input, self.errors)[0]
[   32s] E       UnicodeDecodeError: 'ascii' codec can't decode byte 0xe3 in position 46: ordinal not in range(128)
[   32s] 
[   32s] /usr/lib64/python3.6/encodings/ascii.py:26: UnicodeDecodeError
[   32s] ______________________ TestConvert.test_underscore_option ______________________
[   32s] 
[   32s] self = <tests.test_cli.TestConvert testMethod=test_underscore_option>
[   32s] 
[   32s]     def setUp(self):
[   32s]         # reset cli options
[   32s]         options.overwrite = False
[   32s]         options.dry_run = False
[   32s]         options.no_underscore_emphasis = False
[   32s]         options.anonymous_references = False
[   32s]         options.disable_inline_math = False
[   32s]         self._orig_argv = copy(sys.argv)
[   32s]         if path.exists(test_rst):
[   32s]             with open(test_rst) as f:
[   32s] >               self._orig_rst = f.read()
[   32s] 
[   32s] tests/test_cli.py:41: 
[   32s] _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ 
[   32s] 
[   32s] self = <encodings.ascii.IncrementalDecoder object at 0x7f2d78dae358>
[   32s] input = b'\nTitle\n=====\n\nSubTitle\n--------\n\n**content**\n\n\xe3\x82\xb5\xe3\x83\x96\xe3\x82\xbf\xe3\x82\xa4\xe3\x83\x88\xe3\x83\xab\n------------\n\n`A link to GitHub <http://github.com/>`_\n\nThis is :math:`E = mc^2` inline math.\n'
[   32s] final = True
[   32s] 
[   32s]     def decode(self, input, final=False):
[   32s] >       return codecs.ascii_decode(input, self.errors)[0]
[   32s] E       UnicodeDecodeError: 'ascii' codec can't decode byte 0xe3 in position 46: ordinal not in range(128)
[   32s] 
[   32s] /usr/lib64/python3.6/encodings/ascii.py:26: UnicodeDecodeError
[   32s] _________________________ TestConvert.test_write_file __________________________
[   32s] 
[   32s] self = <tests.test_cli.TestConvert testMethod=test_write_file>
[   32s] 
[   32s]     def setUp(self):
[   32s]         # reset cli options
[   32s]         options.overwrite = False
[   32s]         options.dry_run = False
[   32s]         options.no_underscore_emphasis = False
[   32s]         options.anonymous_references = False
[   32s]         options.disable_inline_math = False
[   32s]         self._orig_argv = copy(sys.argv)
[   32s]         if path.exists(test_rst):
[   32s]             with open(test_rst) as f:
[   32s] >               self._orig_rst = f.read()
[   32s] 
[   32s] tests/test_cli.py:41: 
[   32s] _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ 
[   32s] 
[   32s] self = <encodings.ascii.IncrementalDecoder object at 0x7f2d78dbb320>
[   32s] input = b'\nTitle\n=====\n\nSubTitle\n--------\n\n**content**\n\n\xe3\x82\xb5\xe3\x83\x96\xe3\x82\xbf\xe3\x82\xa4\xe3\x83\x88\xe3\x83\xab\n------------\n\n`A link to GitHub <http://github.com/>`_\n\nThis is :math:`E = mc^2` inline math.\n'
[   32s] final = True
[   32s] 
[   32s]     def decode(self, input, final=False):
[   32s] >       return codecs.ascii_decode(input, self.errors)[0]
[   32s] E       UnicodeDecodeError: 'ascii' codec can't decode byte 0xe3 in position 46: ordinal not in range(128)
[   32s] 
[   32s] /usr/lib64/python3.6/encodings/ascii.py:26: UnicodeDecodeError
[   32s] =============================== warnings summary ===============================
[   32s] tests/test_renderer.py:80
[   32s]   /home/abuild/rpmbuild/BUILD/m2r-0.2.1/tests/test_renderer.py:80: DeprecationWarning: invalid escape sequence \ 
[   32s]     prolog + '\nabc def\ :raw-html-m2r:`<br>`\nghi' + '\n',
[   32s] 
[   32s] tests/test_renderer.py:247
[   32s]   /home/abuild/rpmbuild/BUILD/m2r-0.2.1/tests/test_renderer.py:247: DeprecationWarning: invalid escape sequence \ 
[   32s]     '\na co:\ ``de`` and `RefLink <http://example.com>`_ here.\n',
[   32s] 
[   32s] tests/test_renderer.py:255
[   32s]   /home/abuild/rpmbuild/BUILD/m2r-0.2.1/tests/test_renderer.py:255: DeprecationWarning: invalid escape sequence \ 
[   32s]     '\na `RefLink <http://example.com>`_ and co:\ ``de`` here.\n',
[   32s] 
[   32s] tests/test_renderer.py:707
[   32s]   /home/abuild/rpmbuild/BUILD/m2r-0.2.1/tests/test_renderer.py:707: DeprecationWarning: invalid escape sequence \ 
[   32s]     'This is a\ [#fn-1]_ '
[   32s] 
[   32s] tests/test_renderer.py:708
[   32s]   /home/abuild/rpmbuild/BUILD/m2r-0.2.1/tests/test_renderer.py:708: DeprecationWarning: invalid escape sequence \ 
[   32s]     'footnote\ [#fn-2]_ ref\ [#fn-ref]_ with rst [#a]_.',
[   32s] 
[   32s] -- Docs: https://docs.pytest.org/en/latest/warnings.html
[   32s] ============= 9 failed, 75 passed, 1 skipped, 5 warnings in 0.70s ==============

Complete build log on Leap_15.1