Long projects slugs can cause errors (UnicodeError: label too long)

[mforbes]

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.

[astrojuanlu]

Thanks for reporting @mforbes. I guess you recreated the project as wsu-phys-581-fall-2021?

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

That's right, although we can change it for you https://docs.readthedocs.io/en/stable/faq.html#how-do-i-change-my-project-slug-the-url-your-docs-are-served-at

The label physics-581-physics-inspired-computational-techniques is shorter than 63 characters, so I guess there must be something else going on under the hood.

[mforbes]

@astrojuanlu Yes: and with the shorter slug, everything works fine.

I noticed that the old slug was short enough... I suspect jupyter or nbconvert inserts something at some point during execution, but I never found out exactly where. Everything built fine, but the code cells would not execute.

[stale[bot]]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.

[humitos]

Moving this under the new templates work, since it's more related to the UX when importing a project than anything else.

[agjohnson]

I just came across this in the backlog, is there anything we want to do on the frontend side here? Do we want to handle this at the form validation level in the application instead?

[humitos]

I think we want to do this at the frontend

A warning be displayed to the user at project creation if the generated slug exceeds a certain threshold.

I'm not sure we want to have a hard validation form, but just a warning on the UI.

I don't think this is a priority at this point, tho.

[agjohnson]

Gotcha. I'd probably still start this on the backend side then, with field validation and a field error. The front end UX is supplemental to form validation here, and would probably mostly add UX as users type the project name. The front end code would have to reimplement backend code for slug creation, so I'd probably want to lean on the backend for this purpose.

There is a bit nicer UX in an auto-updating slug field, generated from the project name. But so far I'm trying to keep code in the backend as much as possible.

I'm going to remove this from the dashboard roadmap, though there is probably a feature we'll want to add here at some point.

[agjohnson]

Some of the dynamic form additions are in readthedocs/ext-theme#25. I think this particular bug should be solved at the backend though, emitting form validation errors where needed. Eventually the form will have some dynamic display of the project slug, but this would be a new feature for a later release of the dashboard. I'll continue to track the dynamic form pieces in readthedocs/ext-theme#25 and will move this issue back to the application.