Support for files outside Sphinx project (README.md in parent dir) #7000
Comments
|
+1: Reasonable. README is well known and well used file, and it is usually placed at root of the repository. It would be better to provide a way to include it to main documents (usually placed at directory like Note: Sphinx expects all source files are placed under source directory. So it is hard to support external source files. So we have to think how to support it. I thought copying it temporarily is good workaround. |
|
Copying will likely help many simple cases, but what if the README includes a reference to e.g. |
|
@NumesSanguis There is one alternative that you didn't mention above:
You might see as a disadvantage that you have to use reST syntax in your |
|
Thank you for your suggestion @mgeier . That is indeed one way to tackle the issue, but I would argue against that it's objectively not a disadvantage. While obviously I'm familiar with the syntax, that's why I'm using sphinx, it's unfamiliar to many people not / little involved in Python documentation. Markdown is much more common in use, in coding projects of any language. While less advanced, it's faster to write and has a lower barrier of entrance. A quick edit is also done faster. Therefore, it's quite common that a README.md is already in place before starting with any proper documentation using Sphinx. Having to do 1 adjustment to Sphinx to support Markdown is faster than rewriting the whole README into Sphinx. Markdown is already supported and the only problem here is that it's outside the directory. So yes, if I absolutely need it, I can rewrite it to .rst, but I think it would help many people if a .md file outside the docs/ folder is supported. Rewriting it to an .rst would put-up an additional barrier for editors unfamiliar with the reST syntax. |
The release of sphinx 3.0.0 removed some functions that's been deprecated since v1.4. This made the sphinx-extension 'm2r' break. We use m2r to include .md files in the sphinx-docs. Although a PR that seemingly solves the problem is proposed [1], the sole developer of m2r has not been active in a while. It's unknown when and if this fix will be merge and even if, having a dependency on a unmaintained project like m2r makes me feel a bit uneasy. The ideal action would be to use 'recommonmark' for our .md files. However, sphinx and recommonmark does not play nice when the .md files is out of directory, i.e. outside python/docs [2]. That leaves us with two options, either pinning the sphinx version < 3.0.0 and wait for better days, with regards better sphinx/recommonmarks support, or port the CHANGELOG to rst. As it's unknown whether [2] will actually see the day of light or not, porting seems most reasonable at this point in time. To mention it, there is a bias against using .rst for CHANGELOGs and READMEs in the community, with the main points being; 'people are generally more familiar. md' and '.md is easier and faster to write'. But with a already well-defined structure to our CHANGELOG, the overhead is minimal. [1] miyakogi/m2r#55 [2] sphinx-doc/sphinx#7000
The release of sphinx 3.0.0 removed some functions that's been deprecated since v1.4. This made the sphinx-extension 'm2r' break. We use m2r to include .md files in the sphinx-docs. Although a PR that seemingly solves the problem is proposed [1], the sole developer of m2r has not been active in a while. It's unknown when and if this fix will be merge and even if, having a dependency on a unmaintained project like m2r makes me feel a bit uneasy. The ideal action would be to use 'recommonmark' for our .md files. However, sphinx and recommonmark does not play nice when the .md files is out of directory, i.e. outside python/docs [2]. That leaves us with two options, either pinning the sphinx version < 3.0.0 and wait for better days, with regards better sphinx/recommonmarks support, or port the CHANGELOG to rst. As it's unknown whether [2] will actually see the day of light or not, porting seems most reasonable at this point in time. To mention it, there is a bias against using .rst for CHANGELOGs and READMEs in the community, with the main points being that people are generally more familiar with .md and that .md is easier and faster to write. But with a already well-defined structure to our CHANGELOG, the overhead is minimal. [1] miyakogi/m2r#55 [2] sphinx-doc/sphinx#7000
The release of sphinx 3.0.0 removed some functions that's been deprecated since v1.4. This made the sphinx-extension 'm2r' break. We use m2r to include .md files in the sphinx-docs. Although a PR that seemingly solves the problem is proposed [1], the sole developer of m2r has not been active in a while. It's unknown when and if this fix will be merge and even if, having a dependency on a unmaintained project like m2r makes me feel a bit uneasy. The ideal action would be to use 'recommonmark' for our .md files. However, sphinx and recommonmark does not play nice when the .md files is out of directory, i.e. outside python/docs [2]. That leaves us with two options, either pinning the sphinx version to <v3.0.0 and wait for better days, with regards to better sphinx/recommonmarks support, or port the CHANGELOG to rst. As it's unknown whether [2] will actually see the day of light or not, porting seems most reasonable at this point in time. To mention it, there is a bias against using .rst for CHANGELOGs and READMEs in the community, with the main points being that people are generally more familiar with .md and that .md is easier and faster to write. But with a already well-defined structure to our CHANGELOG, the overhead is minimal. [1] miyakogi/m2r#55 [2] sphinx-doc/sphinx#7000
The release of sphinx 3.0.0 removed some functions that's been deprecated since v1.4. This made the sphinx-extension 'm2r' break. We use m2r to include .md files in the sphinx-docs. Although a PR that seemingly solves the problem is proposed [1], the sole developer of m2r has not been active in a while. It's unknown when and if this fix will be merge and even if, having a dependency on a unmaintained project like m2r makes me feel a bit uneasy. The ideal action would be to use 'recommonmark' for our .md files. However, sphinx and recommonmark does not play nice when the .md files is out of directory, i.e. outside python/docs [2]. That leaves us with two options, either pinning the sphinx version to <v3.0.0 and wait for better days, with regards to better sphinx/recommonmarks support, or port the CHANGELOG to rst. As it's unknown whether [2] will actually see the day of light or not, porting seems most reasonable at this point in time. To mention it, there is a bias against using .rst for CHANGELOGs and READMEs in the community, with the main points being that people are generally more familiar with .md and that .md is easier and faster to write. But with a already well-defined structure to our CHANGELOG, the overhead is minimal. [1] miyakogi/m2r#55 [2] sphinx-doc/sphinx#7000
|
+1 Reasonable request. I am also struggling with this, since |
I was struggling with the same issue and couldn't even install the unmaintained The By updating the following files, I was able to get a perfectly rendered
extensions = [
...
"m2r2",
]
source_suffix = [".rst", ".md"]
.. mdinclude:: ../../README.md
.. toctree::
:maxdepth: 2
:caption: Table of Contents:
readme
...
Closes #7000 |
|
Just use myst-parser and theres no need to have any rST 😉
```{include} ../../README.md
``` |
```{include} ../../README.md
:relative-images:
```Will now re-write local images to the correct path |
I'm getting this error when building a similar project:
The command I'm using is:
Any idea? |
|
@maxi-marufo It was reported as #8395. And it's a bug of m2r2. |
|
@chrisjsewell but how do you then include this markdown-page in other rst-pages? and then link it in rst like would work, but it doesn't. And while myST's documentation explains how to include an rst-page inside an md-page (https://myst-parser.readthedocs.io/en/latest/using/howto.html#include-rst-files-into-a-markdown-file), the opposite is now shown. |
It worked well for text in README but it did not work on images in my case. @d3an do we need to include some other extra syntax for images ? |
With this solition I get |
|
|
Just came here to say that this solution works like a charm 👍🏽 |
(replace ' by `) |
|
p.s. with the latest myst-parser, and docutils>=0.17, you can now include Markdown within RST files, with the .. include:: include.md
:parser: myst_parser.sphinx_(see https://myst-parser.readthedocs.io/en/latest/sphinx/use.html#include-markdown-files-into-an-rst-file) |
|
@tk0miya What is actionable here? I see that this is marked for Sphinx 5.0.0 -- but it seems like this support already exists. The request for adding Markdown support is somewhat separate, and already made possible via Both of the directions that users might want to go is possible now, and it's unclear to me what needs to be addressed here for 5.0.0. |
|
Good catch. There are no tasks for this issue. Let's close it! |
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#191The text was updated successfully, but these errors were encountered: