2

I have an image in my README.md that I would like to be displayed in my sphinx docs (/docs/readme.rst). Can someone show me how to use m2r_parse_relative_links to make this work?

The m2r documentation does not include any information on how to use the m2r_parse_relative_links option; it only states one exists. To the best of my knowledge, I believe this option might be set in a conf.py as

m2r_parse_relative_links = True

I have attempted this within my own sphinx documentation and it does not work for me. My project directory structure is:

+--project
|  +-- __init__.py
|  +-- index.rst
|  +-- Makefile
|  +-- make.bat
|  +-- readme.rst
|  +-- docs/
|      +-- _build/
|      +-- _statics/
|      +-- _templates/
|      +-- imgs/
|          +-- test.png
|      +-- 
|  +-- src/
|      +-- main.py
|      +-- README.md

The README.md contains an image

![Test](docs/imgs/test.png)

readme.rst has

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

and conf.py has

m2r_parse_relative_links = True
adam.hendry
  • 4,458
  • 5
  • 24
  • 51
  • 1
    Please show what you have you tried, after you read its documentation: https://pypi.org/project/m2r/ – Steve Piercy Sep 07 '20 at 00:09
  • Configuration of Sphinx is done in `conf.py`, not in `readme.rst`. You do not say if you have configured Sphinx to parse markdown files, if you have installed or configured `m2r`, or if you have built your docs. Please include those details. – Steve Piercy Sep 07 '20 at 06:02
  • @StevePiercy I made mistakes in my repost. I've corrected these. Sphinx is configured to parse markdown files. `conf.py` includes `source_suffix = {".rst": "restructuredtext", ".md": "markdown"}` – adam.hendry Sep 07 '20 at 07:21
  • @StevePiercy Do you know how to get this to work? – adam.hendry Sep 07 '20 at 07:21
  • According to https://github.com/crossnox/m2r2#features, `m2r_parse_relative_links` is an "option to parse relative links into ref and doc directives". It says nothing about images. – mzjn Sep 07 '20 at 07:56
  • @mzjn Can it parse the relative link to an image? For context, see Sphinx GitHub issue #7000 (https://github.com/sphinx-doc/sphinx/issues/7000). I don't want to use `myst-parser` because I want to maintain additional restructuredtext I will put in my `readme.rst` file. – adam.hendry Sep 07 '20 at 08:38
  • I have not used m2r2 myself. I am just quoting the documentation for that option which I presume refers to `:ref:` and `:doc:` (these are *roles*, not directives, btw). – mzjn Sep 07 '20 at 08:46
  • What makes you think you cannot maintain reST in a readme.rst file with MyST? You can use both. See https://myst-parser.readthedocs.io/en/latest/using/intro.html#enable-myst-in-sphinx – Steve Piercy Sep 07 '20 at 11:11
  • @StevePiercy Let me put it another way. I simply don't want to use myst. How can I make this work NOT using myst? – adam.hendry Sep 07 '20 at 17:04
  • I don't know how to make it work with `m2r2`. I would suggest that you file an issue with the project or contact the maintainers for support. – Steve Piercy Sep 08 '20 at 04:45

0 Answers0