1

Lets say I have the following example project

root
|   readme_sphinx_link.md
|
+---docs
|       example.png
|       readme.md
|       
+---docs_sphinx
|   |   make.bat
|   |   Makefile
|   |   
|   \---source
|       |   conf.py
|       |   index.rst
|       |   
|       +---_autosummary
|       |       example_pkg.main.Dummy.rst
|       |       example_pkg.main.rst
|       |       example_pkg.rst
|       |       readme_include.md
|       |       
|       \---_templates
|               custom-attribute-template.rst
|               custom-class-template.rst
|               custom-module-template.rst
|               
\---example_pkg
    |   main.py
    |   __init__.py

where i want to create a sphinx documentation of the example_pkg with the module main.py. While using sphinx, i want to embed the markdown, located in docs to be available in the created html. To achieve this, I tried using myst-parser and a sphinx setup, using autosummary, based on https://stackoverflow.com/a/62613202

Further i tried to follow the FAQ here

https://myst-parser.readthedocs.io/en/latest/faq/index.html#include-a-file-from-outside-the-docs-folder-like-readme-md

to make the markdown available in main.py

main.py

'''
Example main with example class
'''
class Dummy:
    '''
    .. include:: readme_include.md
        :parser: myst_parser.sphinx_
    '''
    def __init__(self):
        '''
        Class constructor
        '''
        pass

As seen in the docstring, I include and parse readme_include.md (in _autosummary) which looks as followed

readme_include v1

```{include} ../../../readme_sphinx_link.md
:relative-docs: docs/
:relative-images:
```

But when running sphinx, i get the following warning and no link was created

D:\..\..\root\readme_sphinx_link.md:5: WARNING: Unknown source document 'D:/../../root/docs/readme' [myst.xref_missing]

But when using this

readme_include v2

```{include} ../../../docs/readme.md
:relative-docs: docs/
:relative-images:
```

There is no error and the readme is parsed and display in the html. But I would like a link to the rendered readme (as shown in the FAQ I refered to), which i am not able to achieve. Maybe I understood something wrong and it is even not possible to do what I want. I also appreciate any other tips to refer to a rendered markdown file in sphinx

Last but not least the content of the readme.md

# Header for readme

This is just a dummy readme for demonstration purposes

Here we see a dummy picture

![example](./example.png)

and readme_sphinx_link.md

See the following link

[Click me for markdown](docs/readme.md)

and both versions of the created sphinx html, where the blue marked was created with readme_include v1, the red marked with readme_include v2

enter image description here

mzjn
  • 48,958
  • 13
  • 128
  • 248
stranger0612
  • 301
  • 1
  • 2
  • 12

0 Answers0