Project: suggest a simple config file on project import wizard #10356

humitos · 2023-05-25T15:18:03Z

As part of the "Import Wizard" steps, we add an extra step now that shows a simple suggestion for a config file v2 (the same we currently have in our documentation) that uses build.os: ubuntu-22.04 and build.tools.python: "3.11".

This is an initial work to show the value we can add to this wizard with something pretty simple. There is more work required on the copy for this intermediate step and the UX (I added a checkbox for now to force the user to read the message, not ideal, but works for now).

Also, it would be good to find a way to highlight the YAML syntaxis using nice colors and add more useful copy to that intermediate page.

Example

Related #10352

As part of the "Import Wizard" steps, we add an extra step now that shows a simple suggestion for a config file v2 (the same we currently have in our documentation) that uses `build.os: ubuntu-22.04` and `build.tools.python: "3.11"`. This is an initial work to show the value we can add to this wizard with something pretty simple. There is more work required on the copy for this intermediate step and the UX (I added a checkbox for now to force the user to read the message, not ideal, but works for now). Also, it would be good to find a way to highlight the YAML syntaxis using nice colors and add more useful copy to that intermediate page. Related #10352

agjohnson · 2023-05-25T16:24:31Z

Just looking at the video really quick, a couple notes:

Agreed on formatting, but I'd probably only do this in the new dashboard. It should be easier there to add formatting to a code block (feel free to take a swing at this page 😉)
Some separation between the page and the code would be nice, a border box or something to make it feel like an editor. This is also something that is easier on the new dashboard
The checkbox would be a good addition for later, I'm not sure of the UX right now. I'm happy if the user just clicks the next button for now I suppose. I don't feel strongly, but the checkbox is probably easy to miss right now, with all of the content above it.

humitos · 2023-05-29T10:25:33Z

The checkbox would be a good addition for later, I'm not sure of the UX right now. I'm happy if the user just clicks the next button for now I suppose. I don't feel strongly, but the checkbox is probably easy to miss right now, with all of the content above it.

I don't think the checkbox is the best UX, either. However, I think it's better if the user miss the checkbox, clicks on next and the form validation shows an error before continuing and the user hopefully will check for/read about this file before proceeding. Otherwise, they will end up importing projects without a configuration file which is what we are trying to avoid here. So, I'm fine keeping it for now.

I think we can remove this checkbox once we implement the dynamic check for the .readthedocs.yaml file and generate a better error message in this step.

readthedocs/templates/projects/import_config.html

humitos · 2023-05-29T10:42:57Z

Some separation between the page and the code would be nice, a border box or something to make it feel like an editor. This is also something that is easier on the new dashboard

I added some minor quick styling here, and I think it looks better and it's fine for now:

agjohnson · 2023-05-30T23:45:11Z

I added some minor quick styling here, and I think it looks better and it's fine for now

I would say that I would still miss this checkbox. It's quite easy to miss being at the end after lots of text and it doesn't have any special formatting to make the user notice it.

The main thing missing from this page is that it's not entirely clear that we're pausing the project creation process and waiting for the user to take steps to prepare their repository. Instead, it feels more like we're just requiring the user reads this page right now.

We can build this up later, but some of this UI would feel much better and cleaner with dynamic elements and some JS. This is not a now thing, it's a next revision thing.

For now though, I don't see us wanting a checkbox in the future and would instead be aiming for something like CircleCI's UI:

There is no checkbox enforcing compliance, but instead there are only 3 options to proceed
It's clear the process wants the user to do something
You can still opt out of this process and you'll just get an explicit error on first build

humitos · 2023-05-31T07:37:07Z

I would say that I would still miss this checkbox. It's quite easy to miss being at the end after lots of text and it doesn't have any special formatting to make the user notice it.

I removed the checkbox.

humitos · 2023-05-31T07:39:21Z

The main thing missing from this page is that it's not entirely clear that we're pausing the project creation process and waiting for the user to take steps to prepare their repository.

This was one of the goal of that checkbox. It clearly said "I've already added a .readthedocs.yaml to my project" and the user has to click on that.

agjohnson · 2023-05-31T09:38:36Z

This was one of the goal of that checkbox. It clearly said "I've already added a .readthedocs.yaml to my project" and the user has to click on that.

Yeah, I understand the direction, but there is more UI required here for the user to understand that we're asking them to do something immediately. The checkbox and text alone was not enough to communicate this to the user.

The copy was passive, so could have been more active/explicit ("Select this checkbox when you have added a configuration file to your repository"), but this feels like a UI hack.

I had to disable strict SSL on Bower due to an error with jQuery: bower/bower#2608 I'm not sure if this is strictly required, but I'm creating a PR in case we need to this in production as well. Related #10356

humitos · 2023-05-31T12:49:56Z

I think we are ready to move forward with this PR after the latest changes. @agjohnson let me know!

This is how it looks now,

readthedocs/templates/projects/import_config.html

humitos · 2023-06-06T13:51:29Z

I'm merging this so it goes out today.

benjaoming

I was wondering what happens if the user clicks "Edit Advanced Options"...

Maybe this checkbox-option should be moved to the config step.

Or removed entirely: My point would be that after this step, the most important thing for all users is to see that a build is running and get a failure/warning when a .readthedocs.yaml wasn't found. Also, the previous use case of visiting "Advanced Options" largely does the same as what the config file offers!

benjaoming · 2023-06-06T13:39:19Z

readthedocs/rtd_tests/tests/test_project_views.py

-        req.user = get(User, profile=None)
-        resp = ImportWizardView.as_view()(req)
-        self.assertEqual(resp.status_code, 302)
-        self.assertEqual(resp['location'], '/projects/foobar/')


This was removed because it got tested in other test cases?

benjaoming · 2023-06-06T13:47:40Z

readthedocs/templates/projects/import_config.html

+# See https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html
+# python:
+#    install:
+#    - requirements: docs/requirements.txt</code>


Later, we should start maintaining the code for these examples in the same docs folders. We could for instance symlink such a file into a Django template folder and then include it. And build it so we know it works :)

Yeah, we need a better way to track these config file suggestions. Ideally, we should use the same everywhere when possible (docs, import step, dashboard, etc)

Now that this is merged, it's possible to unify the example file over in #10301 - I'm going to try and see how it works.

humitos · 2023-06-06T13:55:59Z

I was wondering what happens if the user clicks "Edit Advanced Options"...
Maybe this checkbox-option should be moved to the config step.

After the config step, the "Advanced options" step will be shown.

benjaoming · 2023-06-06T14:43:50Z

I'll open a follow-up issue. I'm leaning towards removing "Edit Advanced Options" completely.

I had to disable strict SSL on Bower due to an error with jQuery: bower/bower#2608 I'm not sure if this is strictly required, but I'm creating a PR in case we need to this in production as well. Related #10356

humitos requested a review from agjohnson May 25, 2023 15:18

humitos requested review from a team as code owners May 25, 2023 15:18

humitos requested a review from stsewd May 25, 2023 15:18

auto-assign bot assigned humitos May 25, 2023

humitos mentioned this pull request May 29, 2023

Import wizard: suggest a .readthedocs.yaml file readthedocs/ext-theme#165

Closed

humitos added 2 commits May 29, 2023 12:32

Template: update link

94262ab

Template: add more style to the wizard config suggestion

9a819fa

humitos commented May 29, 2023

View reviewed changes

readthedocs/templates/projects/import_config.html Outdated Show resolved Hide resolved

humitos added 2 commits May 29, 2023 12:43

Template: show the file as code

672620e

Form: swap label/help_text

4e44e80

humitos mentioned this pull request May 30, 2023

Import project: suggest a config file (yaml) readthedocs/ext-theme#166

Merged

Tests: update wizard to add a new step

9d9226b

humitos added 2 commits May 31, 2023 09:37

Remove checkbox from suggested YAML file page

9eeeb5f

Suggested YAML file CSS style

4090fa0

Test: re-add self.data to test class

e9b78db

Use CSS class to style the YAML shown at import step

5727471

Add required variable in tests

9bdcbec

humitos mentioned this pull request May 31, 2023

Bower: disable strict-ssl #10370

Merged

agjohnson reviewed Jun 1, 2023

View reviewed changes

readthedocs/templates/projects/import_config.html Outdated Show resolved Hide resolved

readthedocs/templates/projects/import_config.html Outdated Show resolved Hide resolved

agjohnson approved these changes Jun 1, 2023

View reviewed changes

humitos added 2 commits June 1, 2023 09:23

Minor style for import config step

dbb0aa9

Split phrase to avoid scrolling

c9bd407

humitos merged commit 911234e into main Jun 6, 2023

humitos deleted the humitos/import-wizard-config-suggestion branch June 6, 2023 13:51

benjaoming reviewed Jun 6, 2023

View reviewed changes

This was referenced Jun 6, 2023

Project import: "Edit Advanced Options" #10392

Closed

Docs: Configuration file how-to guide #10301

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Project: suggest a simple config file on project import wizard #10356

Project: suggest a simple config file on project import wizard #10356

humitos commented May 25, 2023 •

edited

Loading

agjohnson commented May 25, 2023

humitos commented May 29, 2023 •

edited

Loading

humitos commented May 29, 2023

agjohnson commented May 30, 2023

humitos commented May 31, 2023

humitos commented May 31, 2023

agjohnson commented May 31, 2023 •

edited

Loading

humitos commented May 31, 2023 •

edited

Loading

humitos commented Jun 6, 2023

benjaoming left a comment

benjaoming Jun 6, 2023

benjaoming Jun 6, 2023

humitos Jun 6, 2023

benjaoming Jun 6, 2023

humitos commented Jun 6, 2023

benjaoming commented Jun 6, 2023

Project: suggest a simple config file on project import wizard #10356

Project: suggest a simple config file on project import wizard #10356

Conversation

humitos commented May 25, 2023 • edited Loading

Example

agjohnson commented May 25, 2023

humitos commented May 29, 2023 • edited Loading

humitos commented May 29, 2023

agjohnson commented May 30, 2023

humitos commented May 31, 2023

humitos commented May 31, 2023

agjohnson commented May 31, 2023 • edited Loading

humitos commented May 31, 2023 • edited Loading

humitos commented Jun 6, 2023

benjaoming left a comment

Choose a reason for hiding this comment

benjaoming Jun 6, 2023

Choose a reason for hiding this comment

benjaoming Jun 6, 2023

Choose a reason for hiding this comment

humitos Jun 6, 2023

Choose a reason for hiding this comment

benjaoming Jun 6, 2023

Choose a reason for hiding this comment

humitos commented Jun 6, 2023

benjaoming commented Jun 6, 2023

humitos commented May 25, 2023 •

edited

Loading

humitos commented May 29, 2023 •

edited

Loading

agjohnson commented May 31, 2023 •

edited

Loading

humitos commented May 31, 2023 •

edited

Loading