Projects: project creation form configuration file example/templates

[agjohnson]

trafficstars

This is the third step we described in #10342

In this step, we will start to add UI to our project creation pages and show the user example/template configuration files for their project. This will have it's own set of phases, but to start we are only talking about a fairly minimal UI:

• Project creation form wizard gets a new step that just shows the user an example configuration file to add
  • Show a template that works for most projects
  • Maybe a second/fallback example option that replicates the current defaults that we're deprecating?
  • Our documentation probably shows these same examples as well

Eventually, the later versions of this might be a little smarter, but that doesn't need to hold up design at this phase. We'll want to get this feature in front of user first. Some additions we're pushing off until later:

• Granular configuration file examples for alternative build tools
  • We'd have a selection field with "Sphinx", "Mkdocs", etc. "Docusaurus" shows an example of using Docusaurus with our config file. This would be more direct marketing of build jobs/commands and custom doc tooling.
• Detection of a missing configuration file without building
  • We'd need a secondary task for this, to avoid triggering and failing a build.
  • For now, okay to guide the user with steps and a failing first build might be common. This might be the case even if we check for a file existing though

[ericholscher]

Is this what we just shipped?

[agjohnson]

We shipped the first part of this work, but the other half of this issue still needs some discussion and planning. We can keep this issue around or break out issues for the remaining parts of this issue that we haven't added yet.

The most important is that the next update to the project creation form wizard will be that the configuration file will use dynamic content to show the user relevant examples for the tool they are trying to use for their project. This might just be a new dashboard thing only though.

[humitos]

This could be slightly related to https://github.com/readthedocs/readthedocs.org/issues/11187 in some way.

[ericholscher]

Goal here is to do this after improving our docs for other tool support.

[agjohnson]

For the initial pass here, we can add to the list of Example configuration for dropdown with basic examples -- anything that requires just our configurartion file.

The next phase of this would be to link out to documentation pages for complex examples -- anything that requires additional JS/template/etc changes. We need documentation pages for these however.

[humitos]

I jumped into this today and I found it requires https://github.com/readthedocs/ext-theme/issues/184 as well. The frontend is not prepared to add another config file example easily, unfortunately. I will jump there and see if I find an easy way to do this.

[agjohnson]

Ah I just reviewed your PR, I asked about this. I think it should be easy enough to trigger the tabs from the dropdown, and I'd like to retain the dropdown if possible. I'll poke this really quick, we can always revert to a dropdown later if it is complicated.

[agjohnson]

Actually, yeah, it was super simple.

Screencast from 2024-06-06 14-33-51.webm

Tab content is example only, you can reuse what you did.

diff --git a/readthedocsext/theme/templates/projects/import_config.html b/readthedocsext/theme/templates/projects/import_config.html
index acc68dc..0454316 100644
--- a/readthedocsext/theme/templates/projects/import_config.html
+++ b/readthedocsext/theme/templates/projects/import_config.html
@@ -24,8 +24,9 @@
       <input type="hidden" name="tool" value="sphinx">
       <span class="text">Sphinx</span>
       <i class="dropdown icon"></i>
-      <div class="menu">
-        <div class="item" data-value="sphinx">Sphinx</div>
+      <div class="menu" data-bind="semanticui: { tabmenu: {}}">
+        <div class="item" data-tab="sphinx">Sphinx</div>
+        <div class="item" data-tab="mkdocs">Mkdocs</div>

         {% comment %}
           Adding a second option here will require a bit of JS or FUI:
@@ -40,6 +41,9 @@
     </div>
   </div>

+  <div class="ui tab" data-tab="sphinx">Sphinx</div>
+  <div class="ui tab" data-tab="mkdocs">Mkdocs</div>
+
   <div class="ui mini padded inverted scrolling segment">
     <div class="ui top attached label">
       <code>.readthedocs.yaml</code>