You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Is your feature request related to a problem? Please describe.
Many Python repositories have a structure similar to:
project/
docs/
conf.py
index.rst
src/
README.md
This README is perfect for writing the project's introduction and some minimal usage examples. GitHub also renders these README's on the landing page (not when in the docs folder). This README is often in the format of Markdown, because in multi-contributer projects, this is the most familiar format.
Good documentation includes an introduction, which the README is perfect for, but currently you cannot include this README in the toctree, because it is outside the docs/ folder.
Describe the solution you'd like
One of the following:
Allow toctree parsing of source files outside the Sphinx project (which allows the extension recommonmark to parse the Markdown formatted README.md)
Allow passing on of a .md file to an extension before trying to parse the file as reST with the .. include:: ../README.md statement.
Is your feature request related to a problem? Please describe.
Many Python repositories have a structure similar to:
This README is perfect for writing the project's introduction and some minimal usage examples. GitHub also renders these README's on the landing page (not when in the docs folder). This README is often in the format of Markdown, because in multi-contributer projects, this is the most familiar format.
Good documentation includes an introduction, which the README is perfect for, but currently you cannot include this README in the toctree, because it is outside the
docs/folder.Describe the solution you'd like
One of the following:
recommonmarkto parse the Markdown formatted README.md).mdfile to an extension before trying to parse the file as reST with the.. include:: ../README.mdstatement.Describe alternatives you've considered
.. include:: ../README.mdin areadme_link.rstfile (also mentioned in issue: ..include:: statement doesn't parse markdown files correctly #2840).Problem: Parses the
.mdfile as reSTsys.pathinconf.pylike:sys.path.insert(0, os.path.abspath('..'))Problem: Somehow this doesn't work for me
README.mdProblem: Is not cross-platform (does not work on Windows)
maketime with a function.Problem: Far from ideal, needlessly making files.
.. mdinclude:: ../README.md; Only option working for me.Problem: Using
extensions = ['m2r', 'recommonmark'](or reversed list) gives the error:source_suffix '.md' is already registeredin them2rlibrary.Additional context
.. include::, only to give extensions an interface to do so).recommonmarkto support Markdown files outside the toctree directory: Support for ..include to parse Markdown files (README.md in parent dir) readthedocs/recommonmark#191