Readthedocs.org: README.md not found

[yalp]

Hi and thanks for the readthedocs.org project,

I'm using readthedocs.org and mkdocs for the following project:

https://github.com/Orange-OpenSource/fiware-cepheus/

All docs are in 'doc' and only have README.md files (as github displays them by default), and using the following mkdocs.yml with explicit pages:

site_name: Fiware-Cepheus
repo_url: https://github.com/Orange-OpenSource/fiware-cepheus
site_description: FIWARE Cepheus Documentation
docs_dir: 'doc'
markdown_extensions: [toc,fenced_code]
theme: readthedocs
pages:
- 'Home': 'README.md'
- 'Cepheus-CEP':
  - 'Overview': 'cep/README.md'
  - 'Configuration': 'cep/configuration.md'
  - 'NGSI mapping': 'cep/mapping.md'
- 'Cepheus-Broker': 'broker/README.md'

mkdocs is working fine localy (mkdocs 0.14.0, pip pip 7.1.2, python 2.7) to generate the doc but fails during build on readthedocs.org:

ERROR   -  file not found: /home/docs/checkouts/readthedocs.org/user_builds/fiware-cepheus/checkouts/latest/doc/README.md 
ERROR   -  Error building page README.md 

I expected not to be forced to use index.md if all pages are explicitly listed in the mkdocs.yml.

Am I wrong ?

[yalp]

Workaround: I moved the contents all of README.md files to index.md and it now works correctly.

[alasdairdc]

I've just noticed similar behaviour. Contrary to what is stated in https://read-the-docs.readthedocs.org/en/latest/builds.html

Then Mkdocs will build any files with an .md extension. If you have a README.md, it will be transformed into an index.md automatically.

What it actually does is create a directory called README with an index.html file inside it. This is not the behaviour required. It should create the index.html at the level the README.md was and not README/index.html

[ugocupcic]

Is this what's breaking all our docs?

We now have to access the docs at http://sr-build-tools.readthedocs.org/en/latest/README/ instead of simply http://sr-build-tools.readthedocs.org

Cheers,

Ugo

[mvidner]

Me too: the top page, https://installation-images.readthedocs.org, does not work but https://installation-images.readthedocs.org/en/latest/README/ does.
Thanks for the site!

[mvidner]

While I would prefer RTFD to automatically display the README.md files similarly to what GitHub does, it would be also fine to specify it in mkdocs.yml. But I am not able to do that; am I missing something?

[stsewd]

Hi all!, I think this feature (renaming README files to index files) was removed. The docs needs to be updated (#3498 )

[stsewd]

Docs updated on https://github.com/rtfd/readthedocs.org/pull/3498/commits/d907524ddec69c2530324d9c6cc7011830a209d8 (merged).

[DannyBen]

I see this is still an open issue, and I believe I have seen several issues in regards to the README.md and index.md relationship. Can someone comment on where it stands?

Specifically, I am very much interested to know if there is a way to configure ReadTheDocs to simply use README.md as the index file - as is the practice on GitHub itself and GitHub Pages. this will make it fully compatible across three platforms.

[stsewd]

@DannyBen no, there isn't a way of serving the README file as index. I the past rtd was renaming the README to index, but that's isn't supported anymore. Maybe https://github.com/rtfd/readthedocs.org/pull/3635 can help to people realize that an index file is needed.

[DannyBen]

Thanks a lot. I see the PR is open and I am unsure of the vibe there: Is it a feature that will make it (back?) in? Or is the plan to leave it as "index is the only index"?

[stsewd]

I think is just index the only index. The PR is more to always have an index to serve, so the user doesn't think that their docs are broken or something.

[DannyBen]

I see. I wish it was different - I really like cross-platform compatibility, and was hoping I can use the same repo for both GitHub pages and RTD.

[stsewd]

I think this needs a design decision, otherwise the issue is solved as we don't serve README files as index

[DannyBen]

Well, as it seems this issue is one comment away from being closed, I leave you with food for thought:

There is only something to gain, and probably nothing to lose, by having a logic that shows index.md if found, and falls back to showing README.md if not. No dirty tricks needed, no copying of anything. Just a fallback.

[stsewd]

Well, I kind of think this should be a sphinx/mkdocs option. But I also discovered this https://github.com/mkdocs/mkdocs/issues/321, as some users were depending on the rename step.

What about just creating a symbolic link?

I also believe that the original issue was because rtd was renaming the README file at that time. Also the recommended layout is this https://www.mkdocs.org/user-guide/writing-your-docs/#file-layout

For the sphinx side, you can use the include directive too https://stackoverflow.com/questions/46278683/include-my-markdown-readme-into-sphinx/46286751#46286751

[stsewd]

Just commenting that mkdocs already handles this https://www.mkdocs.org/user-guide/writing-your-docs/#index-pages, README files are converted to index files.

For sphinx, the include directive is still valid, or use this method for md files inside rst https://github.com/sphinx-doc/sphinx/issues/2840#issuecomment-284863143

@DannyBen let me know if that solves your problem or if there is something else to consider here.

[stsewd]

For sphinx we have this issue open https://github.com/rtfd/readthedocs.org/issues/2483, and we are also considering the mkdocs case (which I think is already solved by mkdos itself)

So, I'm closing this in favor of https://github.com/rtfd/readthedocs.org/issues/2483