Addons: create project admin page to configure addons

[humitos]

The new addons project will give users a lot of flexibility: we will eventually allow them to use the JSON response to build anything they want on the frontend (see readthedocs/addons#13) and also because they could also inject the web-components by hand.

However, for the most common use case (no "development configuration") we still want to provide a way to customize some of the addons like "Default filter" on search, the root_selector for docdiff and others. I'm thinking all these things could be a page (or Addons subpages -- like one per addon: Addons -> Search) with a simple form on the project Admin for now.

Things we want to expose to configure currently (there will be more, sure):

• Docdiff:
  • enabled/disabled
  • root_selector: tells Docdiff the selector to perform the diff against the two versions
  • additions and/or deletions (see Docdiff: configure deletions/additions addons#101)
• External version warning:
  • enabled/disabled
• Non latest version warning:
  • enabled/disabled
  • Javascript logic to make the comparison (see Notifications: logic behind non-latest version addons#71)
• Search
  • enabled/disabled
  • Default filter (e.g. project: test-builds)
  • Filters (e.g. "Search only on this project", "Include subprojects", etc)
  • Fuzzy (see Search: fuzzy checkbox UI element addons#84)

It may be too soon to start working on this development, but I want to start the conversation to understand if we all are in the same page.

I'd like to start collecting opinions here because there are different ideas around how to do this and I'd like to think more deeply on them. We can always say: "These are the defaults and there is no way to change them unless you inject the web-components by yourself and pass attributes", like: <readthedocs-search default-filter="project: test-builds"></readthedocs-search>, which is totally valid as well (in particular at this stage)

[agjohnson]

we still want to provide a way to customize some of the addons like "Default filter" on search

+1 here, for very common options at least.

These are the defaults and there is no way to change them unless you inject the web-components by yourself and pass attributes"

This is definitely an option too, though I might save this option for more advanced customization though? I'd say for basic configuration adding UI is indeed the way to go.

I'm thinking all these things could be a page (or Addons subpages -- like one per addon: Addons -> Search) with a simple form on the project Admin for now.

Hrm, I'm in between options here myself. I might lean towards the tabbed interface with multiple form instances. It's a little bit harder to get initial page load correct, but the overall UX is quite nice. It saves us from redundant views/templates too.

• Single form instance with multiple field sets
  • 👍 Single form, no added UI need. Easy to handle errors.
  • 👎 Potentially a very long form. Harder to break apart later.
• Multiple form instances passed to single view/template. Tabbed interface for each addon component
  • 👍 Nice UX. Short forms.
  • 👎 Hard to handle errors because of tabs
• Multiple views for each form, subpages of addons admin page
  • 👍 Nice UX. Short forms. Easy to handle form errors
  • 👎 Potentially redundant template work. Needs a new pattern for project admin sub sub page (Project -> Settings -> Addons -> Docdiff)

---

So overall, I'd probably say we'd be safe if we implement these all as small, individual forms, and can aim for a single project settings subpage. I don't think we're describing anything else, but I'd only implement the templates on the new dashboard.

[agjohnson]

Also, related to my comment on beta opt out in chat, this UI could be something that we add more immediately too. Same pattern as above, but the form option is "Opt in to addons beta", which sets the Version.addons. Or perhaps something else, as we want future versions opted in as well.

This would be an opt-in mechanism we can point users to, and opt-out mechanism if the project has immediate problem, and a reason to point to the new dashboard.

[humitos]

Also, related to my comment on beta opt out in chat

In general, I'd like you to add links when referencing things we talked about outside the issue itself. Otherwise, this is lost next week when the people involved in that chat lose their memory. Besides, it's just a black box for people that were not involved.

[humitos]

@agjohnson you mentioned really good points here. I'll think more about them because I'm not clearly visualizing the different approaches yet, but looks like an interesting conversation to have maybe sooner than later

[humitos]

Note for my future self: allow users to configure "which version to compare against" on docdiff. See readthedocs/addons#154

[humitos]

We already have a customer asking to change the positioning. Currently, it's botton-right, but we have other positions already implemented. See https://github.com/readthedocs/readthedocs-client/blob/f74dfbacf490a1080ff728290dc3b39b9221f9cf/src/flyout.css#L12-L30

I'd like to be able to configure these pre-defined settings via the admin page of the project itself.

Context: https://readthedocs.slack.com/archives/C029M3W01KR/p1699452339345109

[humitos]

Also, related to my comment on beta opt out in chat, this UI could be something that we add more immediately too. Same pattern as above, but the form option is "Opt in to addons beta", which sets the Version.addons.

This is already implemented in #213 and we are pointing users to this page when they ask for this.