-
-
Notifications
You must be signed in to change notification settings - Fork 2.1k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
..include:: statement doesn't parse markdown files correctly #2840
Comments
The include directive only reads a text from specified file and put it on the position. At this moment, there is no way to include markdown document into reST one. |
Now I close this issue. |
As this answer wasn't very satisfying to me I investigated further and found the following solution. It is possible to use the https://recommonmark.readthedocs.io/en/latest/#autostructify One may create a symbolic link to the |
I've made a patch to allow this via |
@eric-wieser If I understand correctly, this patch would allow to easily integrate markdown files by using As I see that this PR is not yet merged, do you (or anyone else 😁) know by any chance how could I use it with readthedocs (i.e., how to tell to readthedocs to use a particular version of sphinx, namely, #7739)? Thanks a lot |
If you have a sphinx extension that supports
Yes - you can a line like this, swapping the commit sha for the one containing my patch: https://github.com/pygae/galgebra/blob/master/doc/readthedocs-pip-requirements.txt#L7-L9 |
Thanks @eric-wieser, Here are the steps that I followed, and modified 4 files: In import recommonmark
from recommonmark.transform import AutoStructify
extensions = [..., 'recommonmark']
# Mention this on the reconmark doc
def setup(app):
app.add_config_value('recommonmark_config', {
# 'url_resolver': lambda url: github_doc_root + url,
'auto_toc_tree_section': 'Contents',
'enable_math': False,
'enable_inline_math': False,
'enable_eval_rst': True,
'enable_auto_doc_ref': True,
}, True)
app.add_transform(AutoStructify) In the dependencies:
- python>=3.5
#- sphinx>=1.4 # Get WIP version of sphinx with MD fix
- pip
- ...
- pip:
- git+https://git@github.com/sphinx-doc/sphinx.git@5460ad6925199b57b27b7d059825d3560872edbb#egg=sphinx
- recommonmark And in the index.rst, added: Contents:
.. toctree::
:maxdepth: 1
file And finally, in .. includedoc:: ../file.md But it doesn't seem to work, and the webpage remains empty. And in the build log I have:
Any idea what is wrong here? |
5460ad6 is the wrong commit, you need to edit that to be the one you want. Your other steps look fine. |
Inspired by this issue comment and this example, I try to combine .rst restructured text files (for automatically generated documentation) with .md markdown files (for manual documentation), using the CommonMark parser. This works well (after #2841) when including markdown files in a toctree, but does not seem to work for
.. include::
statements.E.g. with the statement
.. include:: ../README.md
inside the (restructured text)INDEX.rst
master file, the contents of README.md file are not parsed as markdown text but as restructured text!What is the recommended way to include in the Sphinx documentation markdown files that typically reside in the root of a package (such as README.md, CHANGELOG.md or CONTRIBUTING.md), while parsing them correctly as markdown files?
The text was updated successfully, but these errors were encountered: