Details

If the project slug is too long, then building the documentation on RtD may introduce
cryptic errors that are hard to debug, and difficult to fix.

For example, when trying to build documentation under the project with slug
physics-581-physics-inspired-computational-techniques I encountered the following
warning:

/home/docs/checkouts/readthedocs.org/user_builds/physics-581-physics-inspired-computational-techniques/conda/latest/lib/python3.9/site-packages/jupyter_client/localinterfaces.py:259:
UserWarning: Unexpected error discovering local network interfaces: encoding with 'idna'
codec failed (UnicodeError: label too long)

and the output from my Jupyter notebooks failed to render.

The cryptic nature of this warning is due to python issue
32958 wherein the true nature of the issue was
revealed to be a portion of a generated URL exceeding 63 characters.

Since it is very difficult/impossible to view the actual error logs on RtD, and
difficult to replicate these errors on another system, this is a subtle issue for users
to try to diagnose and fix.

On top of this, changing the slug directly is not permitted, making recovered difficult
even when diagnosed.

In my case, the fix was to delete and re-create the project, manually selecting a short
project name to that a reasonable slug was generated. This is not bad if the project is
new and the URL is not out in the wild. Alternatives are discussed in issue 8143.

Expected Result

I would recommend two changes to help users with this potential issue:

1. A warning in the documentation that long slugs may lead to problems. Steps to
   resolving such issues by choosing a shorter project name during project creation
   should be outlined, and a note that the project name can be restored after the slug
   is generated.

2. A warning be displayed to the user at project creation if the generated slug
   exceeds a certain threshold. (Since I could not access the log files, I cannot see
   exactly what is cause the issue, and hence cannot recommend how much padding should
   be given with this threshold yet.)

   Ideally, some way of editing the slug could be provided, but since slug creation
   needs to be automated to avoid conflicts, another nice solution would be for the
   proposed slug to be updated in real time as the user changes the project name.

Actual Result

The project name is chosen from the source repository, and if long, leads to a long slug
that may cause cryptic errors for the user in the future that are very difficult to
resolve.