miyakogi / m2r Goto Github PK
View Code? Open in Web Editor NEWMarkdown to reStructuredText converter
License: MIT License
Markdown to reStructuredText converter
License: MIT License
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?
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.
The conversion of markdown links with title does not work:
[http://localhost:8888](http://localhost:8888 "Jupyter Notebook")
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.
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.
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 ==============
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!
It would be nice to keep PyPI releases and git tags in sync :)
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?
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.
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>
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.
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.
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.
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
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 — 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> »</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> <<a class="reference external" href="https://github.com/CookPete/auto-changelog">https://github.com/CookPete/auto-changelog</a>>`_.</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> <<a class="reference external" href="https://github.com/hexonet/python-sdk/commit/a9ec1a1547637535220b33eb86a8172a53634879">https://github.com/hexonet/python-sdk/commit/a9ec1a1547637535220b33eb86a8172a53634879</a>>`_</li>
<li>updated changelog <cite>``9e775a8`</cite> <<a class="reference external" href="https://github.com/hexonet/python-sdk/commit/9e775a850af227ecfd227b3b838f989daf63edff">https://github.com/hexonet/python-sdk/commit/9e775a850af227ecfd227b3b838f989daf63edff</a>>`_</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> <<a class="reference external" href="https://github.com/hexonet/python-sdk/commit/c5601beb264c7b7e763e88e11aafcc93da310edd">https://github.com/hexonet/python-sdk/commit/c5601beb264c7b7e763e88e11aafcc93da310edd</a>>`_</li>
<li>fix six import paths <cite>``e304262`</cite> <<a class="reference external" href="https://github.com/hexonet/python-sdk/commit/e3042628792eefce6168b93220308b138647c8f0">https://github.com/hexonet/python-sdk/commit/e3042628792eefce6168b93220308b138647c8f0</a>>`_</li>
<li>set version 1.2.4 <cite>``655b886`</cite> <<a class="reference external" href="https://github.com/hexonet/python-sdk/commit/655b88658c9c0b1db1be39af8700eb900a19ec87">https://github.com/hexonet/python-sdk/commit/655b88658c9c0b1db1be39af8700eb900a19ec87</a>>`_</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> <<a class="reference external" href="https://github.com/hexonet/python-sdk/commit/bd7dc80c9decaccb480333aa4fe51db0c3722389">https://github.com/hexonet/python-sdk/commit/bd7dc80c9decaccb480333aa4fe51db0c3722389</a>>`_</li>
<li>set version to 1.2.2 <cite>``5642b54`</cite> <<a class="reference external" href="https://github.com/hexonet/python-sdk/commit/5642b54c25dd3410f699fb54e0f97a4ee1957109">https://github.com/hexonet/python-sdk/commit/5642b54c25dd3410f699fb54e0f97a4ee1957109</a>>`_</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> <<a class="reference external" href="https://github.com/hexonet/python-sdk/commit/d3fa6ae84e8bc0c6ec941964445085b5ea3f3da6">https://github.com/hexonet/python-sdk/commit/d3fa6ae84e8bc0c6ec941964445085b5ea3f3da6</a>>`_</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> <<a class="reference external" href="https://github.com/hexonet/python-sdk/commit/09997081ddf7c65a6f25fa1827cfb07fd68f82c5">https://github.com/hexonet/python-sdk/commit/09997081ddf7c65a6f25fa1827cfb07fd68f82c5</a>>`_</li>
<li>updated changelog <cite>``eb5e6d4`</cite> <<a class="reference external" href="https://github.com/hexonet/python-sdk/commit/eb5e6d408f088b34172414ed9283fb0fc20e3df3">https://github.com/hexonet/python-sdk/commit/eb5e6d408f088b34172414ed9283fb0fc20e3df3</a>>`_</li>
<li>set version 1.2.1 <cite>``2d98115`</cite> <<a class="reference external" href="https://github.com/hexonet/python-sdk/commit/2d9811500081c0940e3f340af9265b1c66f36893">https://github.com/hexonet/python-sdk/commit/2d9811500081c0940e3f340af9265b1c66f36893</a>>`_</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> <<a class="reference external" href="https://github.com/hexonet/python-sdk/commit/fa7403a9b18dc11b9cf8c74da603c12cee01477a">https://github.com/hexonet/python-sdk/commit/fa7403a9b18dc11b9cf8c74da603c12cee01477a</a>>`_</li>
<li>updated changelog <cite>``a0f7e2f`</cite> <<a class="reference external" href="https://github.com/hexonet/python-sdk/commit/a0f7e2f3418d238f2d4884d786c0d62383d3d0c9">https://github.com/hexonet/python-sdk/commit/a0f7e2f3418d238f2d4884d786c0d62383d3d0c9</a>>`_</li>
<li>apiconnector version 1.2.0 <cite>``85ec52f`</cite> <<a class="reference external" href="https://github.com/hexonet/python-sdk/commit/85ec52f18007de6a9d37889cd1b20711968749fa">https://github.com/hexonet/python-sdk/commit/85ec52f18007de6a9d37889cd1b20711968749fa</a>>`_</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> <<a class="reference external" href="https://github.com/hexonet/python-sdk/commit/95e0199073c19f842778d133ceea8d11a7f64ded">https://github.com/hexonet/python-sdk/commit/95e0199073c19f842778d133ceea8d11a7f64ded</a>>`_</li>
<li>added sdk documentation and generator script <cite>``01fe1e0`</cite> <<a class="reference external" href="https://github.com/hexonet/python-sdk/commit/01fe1e0b858690ad95a3e611b9871067af3132be">https://github.com/hexonet/python-sdk/commit/01fe1e0b858690ad95a3e611b9871067af3132be</a>>`_</li>
<li>added changelog and changelog generator script <cite>``a4bd960`</cite> <<a class="reference external" href="https://github.com/hexonet/python-sdk/commit/a4bd9606e5590388fac9f96c5621a9e03fd125c6">https://github.com/hexonet/python-sdk/commit/a4bd9606e5590388fac9f96c5621a9e03fd125c6</a>>`_</li>
<li>update apiconnector version <cite>``f1804eb`</cite> <<a class="reference external" href="https://github.com/hexonet/python-sdk/commit/f1804eb7bbb48c6e338f5b065dc935820ddcc595">https://github.com/hexonet/python-sdk/commit/f1804eb7bbb48c6e338f5b065dc935820ddcc595</a>>`_</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> <<a class="reference external" href="https://github.com/hexonet/python-sdk/commit/eb2ac4c6458a3620938e429878582e0b1ab93f00">https://github.com/hexonet/python-sdk/commit/eb2ac4c6458a3620938e429878582e0b1ab93f00</a>>`_</li>
<li>ignore .vscode subfolder <cite>``67430e3`</cite> <<a class="reference external" href="https://github.com/hexonet/python-sdk/commit/67430e3419237823839b2946c324a93d7d8de22c">https://github.com/hexonet/python-sdk/commit/67430e3419237823839b2946c324a93d7d8de22c</a>>`_</li>
<li>added .gitignore <cite>``946bc01`</cite> <<a class="reference external" href="https://github.com/hexonet/python-sdk/commit/946bc01b7c3505c28400aca50b9d9d4d4de33684">https://github.com/hexonet/python-sdk/commit/946bc01b7c3505c28400aca50b9d9d4d4de33684</a>>`_</li>
<li>Add files via upload <cite>``aa2bc4d`</cite> <<a class="reference external" href="https://github.com/hexonet/python-sdk/commit/aa2bc4d5f92720c22b7853371ade371e1f95b9dd">https://github.com/hexonet/python-sdk/commit/aa2bc4d5f92720c22b7853371ade371e1f95b9dd</a>>`_</li>
<li>Create README.md <cite>``400e58b`</cite> <<a class="reference external" href="https://github.com/hexonet/python-sdk/commit/400e58b5d2c0db4102ad207c65845a537d95aa93">https://github.com/hexonet/python-sdk/commit/400e58b5d2c0db4102ad207c65845a537d95aa93</a>>`_</li>
<li>fix encoding problem (JIRA: HM-22) + fix in properties() results <cite>``5dc88d4`</cite> <<a class="reference external" href="https://github.com/hexonet/python-sdk/commit/5dc88d4a85f90a7154d0ccde4df33faff0874591">https://github.com/hexonet/python-sdk/commit/5dc88d4a85f90a7154d0ccde4df33faff0874591</a>>`_</li>
<li>support for python2.5, use HTTP instead of HTTPS for the URL <cite>``88cedbf`</cite> <<a class="reference external" href="https://github.com/hexonet/python-sdk/commit/88cedbf82075e19a957349dbc14b2836d99f2117">https://github.com/hexonet/python-sdk/commit/88cedbf82075e19a957349dbc14b2836d99f2117</a>>`_</li>
<li>support for python > 3; also backward compatible <cite>``2756429`</cite> <<a class="reference external" href="https://github.com/hexonet/python-sdk/commit/27564296dcd0e0a388ce45b0e77c467e6d927a31">https://github.com/hexonet/python-sdk/commit/27564296dcd0e0a388ce45b0e77c467e6d927a31</a>>`_</li>
<li>Initial commit <cite>``c89c917`</cite> <<a class="reference external" href="https://github.com/hexonet/python-sdk/commit/c89c917845cda5cef9e4f3a4fb5dc9d022e48006">https://github.com/hexonet/python-sdk/commit/c89c917845cda5cef9e4f3a4fb5dc9d022e48006</a>>`_</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> »</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">
© 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?
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.
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.
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
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?
Block directive at the end of file fails convertsion.
.. directive::
something
<empty lines>
When convert the above, directive body becomes empty.
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
.
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?
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.
/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?
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
And my pypi link is here: https://pypi.python.org/pypi/darkon
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.
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
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?
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
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.
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 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'
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'
).
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.
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:
Please include CHANGES.md
into the pypi distfile; it makes life easier for packagers.
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
.
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?
... that are present in standard .. include directive.
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'])
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
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?
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
I have no problems to write this Commonmark / Markdown:
1. [`LibraryTestCase`](../tests/LibraryTestCase.php)
It renders perfectly as Markdown:
Unless I use it with m2r in a Sphinx build, m2r just does not get it to make the links text teletype:
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)
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/
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?
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
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.
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
This renders (via most Markdown previewers, etc.) to:
cd /opt
)git clone git@someaccount/somerepo.git
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.
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.
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):
cd /opt
)git clone git@someaccount/somerepo.git
If you have a Markdown snippet as seen above in Reference Examples, you'll get a rendering like this:
cd /opt
)git clone git@someaccount/somerepo.git
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.
A declarative, efficient, and flexible JavaScript library for building user interfaces.
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
The Web framework for perfectionists with deadlines.
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
We are working to build community through open source technology. NB: members must have two-factor auth.
Open source projects and samples from Microsoft.
Google ❤️ Open Source for everyone.
Alibaba Open Source for everyone
Data-Driven Documents codes.
China tencent open source team.