Include my README markdown in Sphinx

Question

I would like to include my README.md project in my Sphinx documentation, for example, Can sphinx refer to documents that are not in directories under the root document? - that in the received Sphinx HTML documentation, I click on the link in the table of contents on the welcome page and get to README.md .

To do this, a readme_link.rst document is created containing the lines

 Readme File ----------- .. include:: ../../README.md 

and i add the line

 README <readme_link> 

in etc. index.rst . In addition, my README.md not parsed as Markdown, but simply printed on the page as is.

I thought an alternative idea might be to use the readme_link.md markdown file readme_link.md , but there is no way to include markdown files.

How can I analyze my README.md as markdowns?

(Of course, I don't want to rewrite it as .rst.)

Why m2r doesn't work

I tried to trace the render output from the markdown file inside the .rst file , but this does not work. My README.md has several headers such as

 # First heading some text ## Second heading 1 some text ## Second heading 2 some text 

and I get the error message WARNING:../README.md:48: (SEVERE/4) Title level inconsistent: I understand what “inconsistent header level” means? that I need to use other characters - but after reading them, I realized that the answer relates to rst characters. This would mean that my readme markdown file was not actually converted to rst .

PS: someone else who has tried something like this is https://muffinresearch.co.uk/selectively-include-parts-readme-rst-in-your-docs/

Answer 1

You need to edit your readme_link.rst as follows:

 Readme File =========== .. mdinclude:: ../../README.md 

Please note that the section heading is indicated by = and not - .

Two factors contribute to this.

How to enable it works

The standard include (not mdinclude ) actually reads the contents of the source file and simply copies the raw text instead of the directive. M2R mdinclude first converts the Markdown source to rst , and then, like include , copies this test instead of the directive.

Thus, by the time the rst document is parsed, you have one full rst document from both parents and include files. This complete document should be a valid rst document, which brings us to the second point ...

Header levels must be consistent.

Recall that the reStructuredText specification explains:

Instead of overlaying a fixed number and style order for the section headings, the applicable order will correspond to the order that occurs. The first style encountered will be the external title (such as HTML H1), the second style will be the subtitle, the third will be the subtitle, and so on.

...

You do not need to use all section heading styles and you do not need to use any specific section heading style. However, the document must consistently use the section headings: once the hierarchy of heading styles is established, sections should use this hierarchy.

Therefore, the header levels in the included child must match the header levels in the parent. Since M2R generates an rst document, you (as the end user) do not understand which character is used to define each section level. Therefore, to maintain consistency, you need to use the circuit defined by M2R. Unfortunately, M2R does not document the scheme used (I filed an error report ). However, the schema is defined in the source code :

 hmarks = { 1: '=', 2: '-', 3: '^', 4: '~', 5: '"', 6: '#', } 

As you can see, level 1 headers use the symbol = and level 2 headers use the - symbol. Therefore, the same scheme must be used in the parent readme_link.rst file (you used the opposite).

Alternative solution

The reStructuredText specification also states:

Underlining decoration styles are different from underlining and underlining styles that use the same symbol.

This way you can use the styles of the parent document with underline and underline, and it doesn't matter which characters you used for which level, since M2R seems to use only underline styles. So this would work:

 ----------- Readme File ----------- .. mdinclude:: ../../README.md 

This gives an additional advantage (or a negative one, depending on your point of view) that all headings in the included child document will now be one level lower than they are by themselves. Therefore, the child is more semantically “embedded” in the parent (more than one h1 in one HTML document is often considered not semantic, although technically it is “valid”). Of course, this may or may not be what you want, so it is marked as an “alternative solution”.

Answer 2

There is an alternative approach if you want to include the markdown document in your project as a separate file (and you do not need to insert the contents of this file into the .rst file):

1. Make sure you have the necessary prerequisites

(These steps are also necessary for the accepted answer.)

1.1 Make sure that you have the markdown renderer installed:

 $ pip install -U sphinx>=1.8.3 recommonmark>=0.5.0 

1.2 Add recommonmark to the extensions list in conf.py

1.3 Create a symbolic link to your markdown file

 $ cd docs # or docs/source $ ln -s ../README.md # or to ../../README.md if using docs/source 

2. Include the required markdown file in your documents

Link to the file in your toctree :

 .. toctree:: :maxdepth: 2 :caption: Contents: source/README.md