I have installed a local ReadTheDocs server and think I am very close to having it working. However, while the build of my documentation project says that it is complete, and I can see the generated files under the readthedocs.org/media/html/cadd-faq/latest directory, the View Docs links from the build page generate a 404 page with the following debugging information.
Using the URLconf defined in readthedocs.urls, Django tried these URL patterns, in this order:
^$ [name='homepage']
^support/ [name='support']
^security/
^\.well-known/security.txt$
^search/$ [name='search']
^dashboard/
^profiles/
^accounts/
^accounts/
^notifications/
^accounts/gold/
^builds/
^500/$
^projects/
^api/v2/
^api/v2/docsearch/$ [name='doc_search']
^api/v2/search/$ [name='search_api']
^api-auth/
^api/v3/
^wipe/(?P<project_slug>(?:[-\w]+))/(?P<version_slug>(?:[a-z0-9A-Z][-._a-z0-9A-Z]*?))/$ [name='wipe_version']
^i18n/
^admin/
^media\/epub(?P<path>.*)$
^media\/htmlzip(?P<path>.*)$
^media\/json(?P<path>.*)$
^media\/pdf(?P<path>.*)$
style-catalog/$
^media/(?P<remainder>.+)$ [name='media-redirect']
^__debug__/
The current path, docs/cadd-faq/en/latest/, didn't match any of these.
I can manually point my browser at the URL ".../media/html/cadd-faq/latest/index.html" which redirects to ".../static/html/cadd-faq/latest/index.html" and view the sphinx generated content, so the build appears to really have succeeded. But those pages do not have the ReadTheDocs wrapping content that I would expect the View Docs button to have sent me to, so those URLs are certainly not the right ones either.
That all would seem to indicate that the problem is with something in my ReadTheDocs and/or Django configuration. Any pointers to how to resolve the problem would be appreciated.
So, if you are still with me, just a few comments on my installation. I believe I faithfully followed the instructions at https://docs.readthedocs.io/en/stable/custom_installs/local_rtd_vm.html (and associated pages), but of course, I could have blundered, as there were, in retrospect, some serious steps missing. The extremely helpful, and self answered, instructions at Read the Docs local install: Celery ValueError: signal only works in main thread, through which I got the redis service and celery workers running, took me at least to a place where I started seeing any progress in the build page for my project.
Even then, though, I had a few steps to get to a Build Complete result. First, I had to modify the readthedocs.org/readthedocs/doc_builder/python_environments.py file to allow me to specify an HTTP_PROXY value in my local_settings.py file, and get that sent to the --proxy argument of pip install. (Just setting the environment variables didn't appear to work.) Second, I had to manually pip install the django-storages package into the readthedocs.org/venv environment. And third, I had to add a master_doc specification in my sphinx conf.py file to deal with the fact that readthedocs thinks the default sphinx master_doc is contents.rst, but our version of sphinx thinks it is index.rst.
But that is basically all I did, so I don't see where in my configuration I would have either caused the View Docs links to have the wrong URL, or where I would have removed "^docs/" from the patterns Django is looking for.
I will be glad to post copies of the configuration files I have, but I am afraid I am not sure what the relevant ones to post would be. Let me know what files, including the context diff of my python_environments.py code changes, would be helpful in diagnosing my problem, and I will be more than glad to share them here.
Thanks, Malcolm
The behavior of RTD has changed since version 5 (see changelog). The documentation used to be sync'ed to copy built documentation to a rtd-builds folder, which was then symlinked to from the /public_web_root/ folders. That's no longer the case.
Starting from version 5, they've introduced some proxy middleware called El Proxito, which intercepts the URL before it's passed to nginx, and proxies it to point to the /media/ folders, which as you've noted, contain the built documentation.
RTD support for custom installs has always been pretty lackluster, but it's worse now, since they haven't updated the docs to explain how to properly use El Proxito. The devs of RTD use a docker-compose workflow to set things up, but that comes with its own problems, and the README for that particular module explicitly states that they don't suggest it being used for custom installs. So, in effect, they're leaving you on your own for now.
I'd suggest digging into El Proxito, and trying to install that piece of middleware into your Django configuration to see if you can get the url proxying to work.