miyakogi/m2r

(Sphinx) How to link to markdown files

UncleGoogle opened this issue · 1 comments

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

I would also be interested to use this function...
What is the best way to link ofther md, that gets converted properly in rst using shpinx?