Build Passed But Documentation Not Showing

[bno5761]

Details

I’m trying to create documentation for a new project, but the docs are not rendering online. In order to get everything started, I made just a couple of simple .md files (including one named index.md) and set up the .yml file, as well. To further reduce mistakes, I’ve even copied the format of another RtD I oversee; so I know this new one should work. I’ve connected the project GitHub to readthedocs, and the build passes. But, no docs appear at the appropriate URL. This is similar to issue #2356.

• Read the Docs project URL: vQTLRandom.readthedocs.io
• Build URL (if applicable): https://readthedocs.org/projects/stapletonlab/builds/8939683/
• Read the Docs username (if applicable): jdc5884

Expected Result

Documentation should render correctly.

Actual Result

I receive the dreaded “This page does not exist yet” error.

[dojutsu-user]

Hi @bno5761
It would be helpful for the team to debug this if you can provide the build URL.

[bno5761]

I apologize for not posting it earlier! I've updated the original post to include it.

[stsewd]

Looks like you are missing to change the documentation type to mkdocs (default is sphinx) https://docs.readthedocs.io/en/stable/config-file/v2.html#mkdocs

[bno5761]

I've added a configuration file to the root directory, but the build is now failing to build altogether! This makes me think there's an issue with the configuration file.

[stsewd]

I think the other problem was due a regression in our latest release, I just triggered a new build and it was successful https://readthedocs.org/projects/stapletonlab/builds/8949337/

Also, you may want to use the v2 of the config file https://github.com/jdc5884/StapletonLab/blob/master/.readthedocs.yml (v1 doesn't have the mkdocs setting)

[no-response]

This issue has been automatically closed because there has been no response to our request for more information from the original author. With only the information that is currently in the issue, we don't have enough information to take action. Please reach out if you have or find the answers we need so that we can investigate further. Thanks!

[bno5761]

I apologize for taking so long to respond. The last couple of weeks involved finishing my classes, and I didn't have much opportunity to work on this.

Thanks for helping get the build to pass again. But, the RtD is not allowing the docs referenced in the index.md file to populate. I have only a couple of simple trial documents under /doc_files, but I would still expect them to appear online.

[davidfischer]

For mkdocs, you need to use v2 of the Read the Docs configuration file. Your project is currently using v1 which only supports sphinx for building documentation.

If you update your config file to look like the sample in our documentation except with you want the lines for mkdocs: uncommented and the lines for sphinx: removed.

[bno5761]

It now works! After changing the version and one of the admin settings in Read the Docs (from Sphinx to Mkdocs), it built without error. Thanks so much!