Dashboard: Add awareness/clarity about supporting other solutions than Sphinx

[benjaoming]

NB! PR contains a migration = needs to be merged cleanly into main.

I'm aware that it doesn't make much sense to choose a "generic" builder when there's no build commands available.

These changes are assumed relevant in Dashboard v2.

Edit: Removed "Others" from "Documentation type" options.

[benjaoming]

This was really strange :)

[stsewd]

Not sure if I understand the goal here. I think we are moving away from having more options on the dashboard, and advocate for using a configuration file. Allowing users to change the setting here can be confusing, since it doesn't really work without a config file.

I'm +1 on bringing more awareness to users about using RTD with other tools, but enabling the option in the dashboard isn't necessary.

[benjaoming]

@stsewd you're right that adding the option here leads to another confusing scenario. But I'm already confused by the lack of options :) Maybe the perfect compromise is to keep the help text changes and remove the "Other" option from the select.

[humitos]

These changes are assumed relevant in Dashboard v2.

I think this is the way to go. Why not proposing/discussing these changes there instead?

[benjaoming]

I think this is the way to go. Why not proposing/discussing these changes there instead?

I only touched areas of the codebase (forms and models) that would also work for v2, so definitely avoiding templates.

[humitos]

Yeah, I know. I'm trying to say that, as @stsewd mentioned, I don't think this proposal is the way communicate there are other builders supported. In particular, because "Others" won't do anything and will lead to more confusion to our users. Also, all this section of the dashboard shouldn't be used since the .readthedocs.yaml is the recommended place.

This change should probably re-thought and done directly into the v2 dashboard.

If we want to add something in the current dashboard, we should probably add a note in that page communicating this and linking to the correct page of our documentation.

[humitos]

This is much better! 💯

Pinging @agjohnson since he has probably thought about how to present this in the new templates, and may be good his input here.

Pinging @ericholscher because I assume he would like to explicitly mention other doctools here instead of just saying "other tools than Sphinx and MkDocs" 😉

[ericholscher]

Yea, I think this is a small change, when we already have a big warning at the top of the page? This help text feels overwhelming, I think it should be made much smaller and just link to more information.

[benjaoming]

when we already have a big warning at the top of the page?

That warning doesn't say anything about supporting other tools than Sphinx. So if you look at the page with "normal user's perception", you'll see that RTD looks like a Sphinx-only platform (with a warning about using a configuration file).

I'll be jumping over to the Dashboard v2 work soon, where we can improve the combined UI... just wanna be sure that we push in some of the "good news" so that v1 users (i.e. all current users) aren't kept in the dark about support for other builders. Recall that the old help_text of this field unfortunately makes it look like we only have Sphinx builders.

I think we have a lot of "habbit users" that won't read our newsletters, tweets etc. but will discover information in odd places like this. So I don't really mind overloading the help_text for that reason, it's worth a shot.. in any case, we get rid of the "Sphinx builders" misunderstanding :)

[agjohnson]

Generally speaking, blocks of help_text make forms a bit of an information dump and quite hard to parse through. But for now, verbose help text is still okay in the new templates as I've used a popup for this text, which keeps forms cleaner and easier to parse:

Recall that the old help_text of this field unfortunately makes it look like we only have Sphinx builders.

I'm 👍 on making things truthy for now though, it's better than only mentioning Sphinx. I'd agree that folks aren't necessarily going to find this either though.

I think it should be made much smaller and just link to more information.

👍 this is a good pattern to follow, and it is a good way to seed our documentation with more information. Long term, I'd love to use documentation embedding in our UI for form fields like this, but we'll need more docs to do this.

[benjaoming]

It'd be cool if Django model fields had a help_text AND a doc_url property or some other super-cool way to jump from a form into a how-to or a reference :)

But yeah, if we can just find a nice balance of writing brief help_texts that generally link to documentation, that will definitely benefit users and also help to showcase how an otherwise external documentation website can be made accessible on an application website.

[ericholscher]

I don't think this is an important change, but I'm fine with it. I'd prefer not to discuss it too much, given how little is changing..

[benjaoming]

Don't merge! I've just added a suggestion that needs a migration update :)

[agjohnson]

With regards to how to address this going forward, I think there is some education we need to work into the UI and we need to discuss what we're doing with form UI that is being superseded by our configuration file. We've talked about removing most of these fields for projects using our configuration file, and I think that is the right call still.

The issue here is definitely more of an onboarding problem. If the build type field in the admin UI is where the user is just learning about support for tooling or what the builder executes, we haven't done enough to onboard the user. I mean, we're not doing much/any onboarding in our UI at all, so this isn't surprising.

This is where I think something like a configuration file generator UI, as the first step a new project or new user encounters, would help us¹. It would:

• introduce build backend and other concepts to users
• allow us to enumerate the tools we officially (Sphinx/Mkdocs) and unofficially support (Pelican/etc)
• and could also be how we initially "support" third party build tools like Pelican/etc ²

There are more links out to docs in the new dashboard, but that might not help granular issues like "how do I use Pelican instead?"

Edit: discussion continued here: https://github.com/readthedocs/meta/discussions/116

Footnotes

1. We've talked about this as a CLI command, which is another option, however I'm probably describing a web UI. That way, we're capturing the user at the exact point they are ready to learn about adding a project to RTD. ↩

2. @humitos and I talked about packaging patterns here, to push tooling integration maintenance back towards tooling communities, but we'll probably need to guide users here for a while, until this momentum has built in other tooling communities. ↩

[benjaoming]

@agjohnson I could see how we might address the needs of users that don't want to maintain a configuration file but find it easier to use a UI.. but that shouldn't be assumed or accepted by leaving the current UI as-is, it should be designed. We definitely need to separate this much better, and I think we need to be able to auto-generate a configuration file from a "snowflake" set of database-settings so the migration path is super-easy and obvious. This is where we should start.

But is there an issue open for generating a configuration file for projects that do not have one? And do we even detect that a project doesn't have a config file so we can conditionally show big warnings and helpful suggestions?

[ericholscher]

Closing this, since we're spending way too much time on this. @benjaoming if you want to open a PR with just the conf.py rename, that should be quick to merge.

[agjohnson]

I could see how we might address the needs of users that don't want to maintain a configuration file but find it easier to use a UI

@benjaoming Just for a little more knowledge share here, we're pretty committed at this point to pushing all projects toward our configuration file. The balance to strike with the admin UI won't be to make it a comparable experience, but instead to start deprecating fields in that UI and push more projects towards our configuration file.

There will definitely still be some options in our project admin UI though, it can't go away entirely. Any option that is project level instead of version level is still a good fit for the project admin UI.

Anyways, this is all a ways off, but just noting for background on direction here.

But is there an issue open for generating a configuration file for projects that do not have one?

Hrm I can't find any, but know we've had some discussion in the past. I've opened up https://github.com/readthedocs/meta/discussions/116 for now to discuss this idea more.

And do we even detect that a project doesn't have a config file so we can conditionally show big warnings and helpful suggestions?

We do, but there is more we could be doing to offer suggestions and onboarding. I've long wanted #3399 as a way to emit multiple suggestions/warnings/errors from build processes. Though, we also have multiple areas on the new dashboard primed for this sort of content too, and this doesn't have to be build-driven -- ie: readthedocs/ext-theme#103