recommonmark: source_suffix '.md' is already registered

NumesSanguis commented 4 years ago

Thank you for keeping m2r alive!

I found this repo through your comment in this issue: https://github.com/miyakogi/m2r/issues/51 In that same issue, I asked for a check to be added if .md is already registered. As this issue is also present in m2r2, I would like to ask the same here.

Full issue details:

If in conf.py, you have the following (order is unimportant):

extensions = [
    ...
    # .. mdinclude for Markdown documents
    'm2r2',
    # parse .md documents with sphinx
    'recommonmark',
]

Executing make html will raise the error:

make html
Running Sphinx v3.1.2

abs path: /some/path

Extension error:
source_suffix '.md' is already registered
Makefile:20: recipe for target 'html' failed
make: *** [html] Error 2

A possible solution?

Some modification to the code here?: https://github.com/CrossNox/m2r2/blob/development/m2r2.py#L663-L667

Or can m2r2 and recommonmark not be used in the same documentation?

Related issues:

CrossNox commented 4 years ago

Hello @NumesSanguis, thanks for the issue! I'm gonna try to make some failling tests for this and get it working. Would it be too much of a hassle to ask for a minimal example to see how you are using each tool?

NumesSanguis commented 4 years ago

Actually I'm not too sure anymore why I tried both in the same project. When I started with the documentation for my project years ago, I started with recommonmark, as this was the recommended approach. However, I wanted to include the README.md outside the docs folder. Recommonmark did not support this, but it was possible with m2r. So when I added m2r to the requirements, that issue popped-up. Therefore, I guess the use-case is when you are in the middle of switching from recommonmark to m2r2?

Now almost all my documents are .rst, except for the README, which I include like so:

README.md
docs/
  |- README.rst

README.rst:

.. mdinclude:: ../README.md

hoermannpaul commented 4 years ago

I had the same issue, removing recommonmark resolved it.

I guess recommonmark is adding a parser for .md too, thus the problem.

triggerwaffle commented 3 years ago

remove 'recommonmark' from extention array and add the below code in the bottom of the conf.py it seems to work fine.

github_doc_root = 'https://github.com/rtfd/recommonmark/tree/master/doc/'
def setup(app):
    app.add_config_value('recommonmark_config', {
            'url_resolver': lambda url: github_doc_root + url,
            'auto_toc_tree_section': 'Contents',
            }, True)
    app.add_transform(AutoStructify)

CrossNox commented 3 years ago

I think this can be closed since this is due to recommonmark registering for .md suffix.

MarionMoseby commented 2 years ago

Hey! This issue also pops up when enabling myst_parser, which is needed by sphinx_design. Is there any way of fixing it?

johentsch commented 1 year ago

Hey! This issue also pops up when enabling myst_parser, which is needed by sphinx_design. Is there any way of fixing it?

Also had this issue when adding m2r2 in my conf.py:

extensions = [
    ...,
    "myst_nb", 
    "m2r2",
]

but managed to solve it by changing the order naming m2r2 first.

CrossNox / m2r2