Read-the-Docs Local Instance: Docs are built successfully but cannot be found eror (404)

Hello,

Read the Docs relies on serving the static documentation via an NGINX or another web server. The generated docs are stored in a file system, and the web server is responsible for delivering them when you click on “View Docs”.

The 404 error is usually because the web server (e.g., NGINX) isn’t correctly configured to serve the documentation static files from the right location or the build didn’t produce the expected output.

Here are some steps to diagnose and possibly resolve the problem:

1. Check the Build Output: Ensure that the documentation is indeed being built successfully and stored in the expected location on the file system. You might want to look into RTD’s build logs or even the build output folder.

2. Web Server Configuration: If you’re using a web server like NGINX, you need to configure it to serve static files from the directory where RTD places built documentation. Ensure the server block (or equivalent) is set up correctly.

   For instance, if using NGINX, you might have a configuration block similar to:

   location /docs/ {
       alias /path/to/your/readthedocs/public_html/;
   }
   

3. Replace /path/to/your/readthedocs/public_html/ with the actual path to your documentation.

4. URL Configuration: Ensure that the Django URL configuration (urls.py) in your local RTD instance is correctly set up to handle the /docs/ prefix.

5. Django’s STATIC Files: Remember that in a production environment, Django doesn’t serve static files itself. They’re typically served by a web server. If you’re trying to access the documentation through the Django development server (runserver), you might face issues. It’s best to configure a web server or use Django’s collectstatic and serve them in the correct manner.

6. Custom Domains or Routes: If you’ve configured custom domains or routes in your RTD settings, make sure they are correctly set and that they don’t conflict with other configurations.

7. Check for Errors: Look into both the RTD logs and the web server logs. They can give more specific details about what’s going wrong.

Best,

Bobby

The 404 error you’re encountering when trying to view the documentation in your local Read-the-Docs (RTD) instance could be due to a few common issues related to the URL routing or the configuration of your RTD instance.

Things to Check:

1. URL Routing in urls.py:

The missing /docs/ prefix suggests that the URL routing isn’t set up correctly for serving the documentation. In your Django project’s urls.py file, ensure that the URLs for serving the documentation are correctly configured.

By default, RTD uses nginx or another web server to serve the static HTML files generated by the documentation builds. However, if you are running it locally without a web server, you need to ensure that Django is serving the static files.

Ensure that in urls.py, you have the correct path for serving the docs. It should look something like this:

from django.conf import settings
from django.conf.urls.static import static

urlpatterns = [
    # Your other routes here...
] + static(settings.MEDIA_URL, document_root=settings.MEDIA_ROOT)

2. Static Files and Media URL Configuration:

Since the docs are served as static files, make sure your static files and media URLs are correctly configured in settings.py.

• STATIC_URL and MEDIA_URL should be properly set:

STATIC_URL = '/static/'
MEDIA_URL = '/media/'

If you’re using Docker or a more advanced setup, make sure the media folder is correctly mapped to where the documentation is built.

3. Build Output Location:

Verify that the documentation is actually being built in the correct directory, typically under the /media/docs/ folder. If the documentation is built elsewhere, update the MEDIA_ROOT or STATICFILES_DIRS in settings.py accordingly.

Check if the documentation HTML files are located in MEDIA_ROOT/docs/<project_name>/en/latest/. If not, adjust the build paths.

4. Check Nginx or Web Server Configuration:

If you’re using Nginx to serve the documentation files, make sure that the Nginx configuration is correctly set to serve the /docs/ path. It should look something like this:

location /docs/ {
    alias /path/to/your/media/docs/;
    autoindex on;
}

Restart Nginx after any configuration changes

5. Check Django Logs for Errors:

You may find more information by checking the Django logs for any errors related to the missing routes or static files:

tail -f /path/to/your/logs/debug.log