Guide doesn't work anymore?

[dschuermans]

Hey,

Stumbled upon your guide by coincidence and it looked useful and straightforward but I've tried following your guide and it appears it's not working anymore as expected.
The link to user-guide.md is not rendered on readthedocs

Any ideas?
I thought it might be because of a missing .md extension in the index.rst file for the uiser-guide entry, but with or without, the result remains the same...

I got my test repo under https://github.com/dschuermans/rtdtest and https://dschuermans-rtdtest.readthedocs.io/

[dschuermans]

Ah, it appears using the # markdown syntax for titles isn't being accepted in the default project setup on readthedocs?

In the build log, I saw some warnings about user-guide being referenced in index.rst but the page did not have a title, so it was being skipped.

When I updated the title from
# Project Name User Guide v0.0.0
to

Project Name User Guide v0.0.0
=====================

the warnings were gone and the page was rendered in the docs:

https://dschuermans-rtdtest.readthedocs.io/en/latest/user-guide.html

However, as you can see, it did not transform the sub-titles with the ## syntax and kept them as-is.

So something is missing somewhere, I just don't know what but I'd guess some kind of config somewhere?

[rick-masters]

Hi Dirk,

Thanks for you feedback and sorry for the troubles.

When I click on links to your readthedocs guide, it takes me to your "stable" version, not the latest.
There is a step in the guide where it directs you to change your default revision in readthedocs to "latest". Did you do that?

When I do navigate to "latest" it showed your document link in readthedocs. So, I suspect you were looking at an older version when you did not see the link.

But with your latest comment, you are saying the title must not have a pound sign. That's odd because my guide has a pound and it is ok. It is possible that they made it more strict since the last time I published but I think we need to do some more troubleshooting to nail that down. Can you retry with the pound sign back in, making sure you are looking at latest revision? Also, can you let me know a good time to look at it is, because it will be hard for me to troubleshoot if you are actively changing it. Thanks!

[dschuermans]

Hi Rick,

Ah sorry, wasn't expecting a response so quickly 😄
Yea, i've changed it so that the default version is the stable one, i'm playing around with latest indeed.

From the build logs before I changed the title from using the pound sign to the underlined version:

[rtd-command-info] start-time: 2021-11-16T16:54:03.116860Z, end-time: 2021-11-16T16:54:03.847158Z, duration: 0, exit-code: 0
/home/docs/checkouts/readthedocs.org/user_builds/dschuermans-rtdtest/envs/latest/bin/python -m sphinx -T -b html -d _build/doctrees -D language=en . _build/html
Running Sphinx v4.3.0
loading translations [en]... done
making output directory... done
building [mo]: targets for 0 po files that are out of date
building [html]: targets for 3 source files that are out of date
updating environment: [new config] 3 added, 0 changed, 0 removed
reading sources... [ 33%] README
reading sources... [ 66%] index
reading sources... [100%] user-guide

looking for now-outdated files... none found
pickling environment... done
checking consistency... /home/docs/checkouts/readthedocs.org/user_builds/dschuermans-rtdtest/checkouts/latest/docs/README.md: WARNING: document isn't included in any toctree
done
preparing documents... done
writing output... [ 33%] README
writing output... [ 66%] index
writing output... [100%] user-guide

/home/docs/checkouts/readthedocs.org/user_builds/dschuermans-rtdtest/checkouts/latest/docs/index.rst:6: WARNING: toctree contains reference to document 'user-guide' that doesn't have a title: no link will be generated
/home/docs/checkouts/readthedocs.org/user_builds/dschuermans-rtdtest/checkouts/latest/docs/index.rst:6: WARNING: toctree contains reference to document 'user-guide' that doesn't have a title: no link will be generated
/home/docs/checkouts/readthedocs.org/user_builds/dschuermans-rtdtest/checkouts/latest/docs/index.rst:6: WARNING: toctree contains reference to document 'user-guide' that doesn't have a title: no link will be generated
/home/docs/checkouts/readthedocs.org/user_builds/dschuermans-rtdtest/checkouts/latest/docs/index.rst:6: WARNING: toctree contains reference to document 'user-guide' that doesn't have a title: no link will be generated
generating indices... genindex /home/docs/checkouts/readthedocs.org/user_builds/dschuermans-rtdtest/checkouts/latest/docs/index.rst:6: WARNING: toctree contains reference to document 'user-guide' that doesn't have a title: no link will be generated
done
writing additional pages... search /home/docs/checkouts/readthedocs.org/user_builds/dschuermans-rtdtest/checkouts/latest/docs/index.rst:6: WARNING: toctree contains reference to document 'user-guide' that doesn't have a title: no link will be generated
done
copying static files... done
copying extra files... done
dumping search index in English (code: en)... done
dumping object inventory... done
build succeeded, 7 warnings.

[dschuermans]

I've also found this on the RTD docs:

https://docs.readthedocs.io/en/stable/intro/getting-started-with-sphinx.html#using-markdown-with-sphinx

I tried adding that line to the conf.py in /docs, but that just fails the build:

Running Sphinx v4.3.0
loading translations [en]... done

Traceback (most recent call last):
  File "/home/docs/checkouts/readthedocs.org/user_builds/dschuermans-rtdtest/envs/latest/lib/python3.7/site-packages/sphinx/registry.py", line 429, in load_extension
    mod = import_module(extname)
  File "/home/docs/checkouts/readthedocs.org/user_builds/dschuermans-rtdtest/envs/latest/lib/python3.7/importlib/__init__.py", line 127, in import_module
    return _bootstrap._gcd_import(name[level:], package, level)
  File "<frozen importlib._bootstrap>", line 1006, in _gcd_import
  File "<frozen importlib._bootstrap>", line 983, in _find_and_load
  File "<frozen importlib._bootstrap>", line 965, in _find_and_load_unlocked
ModuleNotFoundError: No module named 'myst_parser'

The above exception was the direct cause of the following exception:

Traceback (most recent call last):
  File "/home/docs/checkouts/readthedocs.org/user_builds/dschuermans-rtdtest/envs/latest/lib/python3.7/site-packages/sphinx/cmd/build.py", line 279, in build_main
    args.tags, args.verbosity, args.jobs, args.keep_going)
  File "/home/docs/checkouts/readthedocs.org/user_builds/dschuermans-rtdtest/envs/latest/lib/python3.7/site-packages/sphinx/application.py", line 237, in __init__
    self.setup_extension(extension)
  File "/home/docs/checkouts/readthedocs.org/user_builds/dschuermans-rtdtest/envs/latest/lib/python3.7/site-packages/sphinx/application.py", line 394, in setup_extension
    self.registry.load_extension(self, extname)
  File "/home/docs/checkouts/readthedocs.org/user_builds/dschuermans-rtdtest/envs/latest/lib/python3.7/site-packages/sphinx/registry.py", line 433, in load_extension
    err) from err
sphinx.errors.ExtensionError: Could not import extension myst_parser (exception: No module named 'myst_parser')

Extension error:
Could not import extension myst_parser (exception: No module named 'myst_parser')

[rick-masters]

I'm seeing a pound sign at the end of the lines for your titles. I don't think those should be there.

[dschuermans]

I'm seeing a pound sign at the end of the lines for your titles. I don't think those should be there.

Oh right, forgot to remove those.

But with or without, still the same result.

From the markdown spec:

[rick-masters]

I am still seeing the end pound symbols on RTD so I'm wondering if you could force a new build just to be sure its up to date.

[rick-masters]

I forced a new build on my RTD project without changing anything and now the build fails with errors. So, it appears my instructions no longer work with the current RTD software. The soonest I would be able to resolve this is later this afternoon but no guarantees. I'll keep you posted. Please let me know if you find a solution sooner.

I'll try to build more often from now on. I thought the RTD tooling was stable but apparently not. It has been 19 months since I tested a build, though.

[dschuermans]

Okay, I think I managed to get it working:

• Added a .readthedocs.yaml file in the root of the repository: https://raw.githubusercontent.com/dschuermans/rtdtest/master/.readthedocs.yaml
• Added a requirements.txt inside the docs folder:
  https://github.com/dschuermans/rtdtest/blob/master/docs/requirements.txt
• Updated docs/conf.py with the following contents:

  extensions = ['myst_parser']
  
  source_suffix = ['.rst', '.md']
  
  master_doc = 'index'
  project = u'dschuermans-rtdtest'
  

So the yaml file controls the build over at RTD. Inside the yaml file, we tell that python needs to install whatever is specified in the requirements.txt file.
In that file, we list myst_parser and sphinx (version lower than 3?)

At first, had to do a few attempts on modifying the conf.py:
With that version of sphinx, the original source_parsers setting was marked as obsolete and had to be removed.
Since that was the only thing in the file using the CommonMarkParser value, I figured the import statement could be removed too (I have 0 experience with python mind you 😄)

So i'm pretty sure that these changes can be refined further, but my guess is that the CommonMarkParser does not support the # titles

Maybe this can help you on your way to get your guide working again?

Btw, small sidenote i found on the RTD docs:

So maybe if you would've pinned the versions you used at that time, the guide would still work?

[rick-masters]

My build problem was this one: readthedocs/readthedocs.org#8616

For older RTD projects like mine, Readthedocs secretly pinned Sphinx to an old version, which does not work with a recently released docutils version. Readthedocs seems to think this is my configuration problem - I needed to pin docutils to match their secretly pinned v1 Sphinx! But I never wanted to be pinned to old Sphinx in the first place and they don't seem to have an answer for that. So I just deleted my RTD project and created it again. So the sphinx pin is gone and now I can see that the latest version does not work either, as you reported.

By the way, why did you pin sphinx to < 3? Have you tried leaving that out? If you are following their recommendation to pin, why didn't you use a later one like ==4.3.0?

[dschuermans]

By the way, why did you pin sphinx to < 3? Have you tried leaving that out? If you are following their recommendation to pin, why didn't you use a later one like ==4.3.0?

No reason really, during my google searches I stumbled upon some other repo that was using sphinx and had that in their requirements file.
I figured it was needed since I saw a note somewhere that the myst_parser required sphinx version 2.1 or higher

I just tested it without that line and it still works so... Guess it's not needed 😅

[rick-masters]

I'll make sure it works for me as well and then I'll update this guide to include creating those config files.
Thanks for your help.

[dschuermans]

No problem, glad I could be of any help 😄

FYI, the yaml file can be reduced to:

# .readthedocs.yaml
# Read the Docs configuration file
# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details

# Required
version: 2

# Optionally declare the Python requirements required to build your docs
python:
   install:
   - requirements: docs/requirements.txt

[rick-masters]

Fun fact: it appears the .readthedocs.yaml file is not necessary because requirements.txt is honored without it

[dschuermans]

Fun fact: it appears the .readthedocs.yaml file is not necessary because requirements.txt is honored without it

Ah even beter 😃
Good to know, thanks!