rst files into
rst files is easy. But what about a markdown readme
that also lives in a different directory tree?
My python projects have the following structure:
If the readme was formatted as a RST file, this would be no problem: Create
readme.rst in the
doc folder and use the
include directive to
include the readme from the directory above. You would even have fine grained
control over which parts of the file to include.
There are several suggestions out there, but the only elegant one seems to
m2r package (github) which
however is no longer maintained and doesn’t seem to work with the newer sphinx
My current workaround is to add the following in
recommonmarkto the list of extensions
source_suffix = [".rst", ".md"]
- Add the following snippet:
You can see it in action at the AnkiPandas documentation.
You might also enjoy reading this discussion on github that discusses some other approaches (many of which don’t work).
Note: Updated on Mai 23 2021 with an improved version.