Docs: Configuration file how-to guide

[nikblanchet]

This is a how-to guide covering how to create and set up the configuration file. The goal is a narrative document explaining to both the Markos and Riika personae…

1. How to create the .readthedocs.yaml file
2. What the minimum required settings need to be in the file

It will link to the full configuration file reference page for those who want to go into more detail.

---

📚 Documentation previews 📚

• User's documentation (docs): https://docs--10301.org.readthedocs.build/en/10301/

• Developer's documentation (dev): https://dev--10301.org.readthedocs.build/en/10301/

[agjohnson]

We had a conversation around the configuration file being not not correct, I opened up #10302

[agjohnson]

I put up #10303 to update the wrongly tagged required fields. We decided that it would be best to call these three fields required:

• version
• build.os
• build.tools -- this does require a subkey, like python, but none of the subkeys are required, just one subkey is required

[humitos]

build.tools -- this does require a subkey, like python, but none of the subkeys are required, just one subkey is required

To add a little more complexity here, when using build.commands, the build.tools key is not required 😄

[humitos]

Thinking a little more about this, it seems users will benefit a lot from having "template use cases" defined with a working YAML example together:

• run Pelican with build.jobs
• run Docusaurus with build.commands
• recommended way to setup Sphinx on Read the Docs
• config file to use MkDocs without build.jobs nor build.commands
• and more examples

This will probably allow people to just copy and paste these config files to use in their project and make some minor adjustments (probably file paths) to make them work on their projects.

[benjaoming]

Great initiative @nikblanchet 🥇

I could see the goal of the how-to as being able to go from "not having a config file" to "having a minimal config file and being ready to read the reference" - I think that reflects the intro of your PR description?

I like the narrative voice! But yeah, I guess narrating too much will quickly move the scope of the article into explanation, which Diátaxis has a few words to say about :)

I'll try to provide 3 example configuration files and push them into this branch for everyone to review? I'll leave it up to you to include them, but I think the tabbed interface will work really well 😇

[benjaoming]

@nikblanchet I was wondering if you are still around? I would like to propose to the core team to move forward with this initiative very soon in relation to #10342.

Since #10356, we added example code for a .readthedocs.yaml file to the Import Wizard. I would like that code to be maintained in a single location so we maintain all our example code in a single location.

[benjaoming]

@nikblanchet, I hope it's okay that I try to see if I can get your work here merged by making some changes here 👍

[nikblanchet]

I'd lost track of this project. Mind if I take this up this upcoming weekend?

[benjaoming]

That sounds great @nikblanchet 👍 I'll do a bit more work on the PR and perhaps it will be ready for review. But we don't have to rush it - it would be nice to wrap it up on Monday though, since we release on Tuesdays. Not sure if you noticed, but we are making the configuration file mandatory from September, so the how-to became a lot more valuable: https://blog.readthedocs.com/migrate-configuration-v2/

[benjaoming]

@agjohnson

WRT these two items, I'd like to have a decision + solution for how to move forward.

2. The 3 templates that are added, especially the bare template for custom build.commands
3. Do we call the third tab "Other tools" or is there a better term?

To give some context:

• On many occasions, I've seen it noted that we need to promote using other documentation tools than Sphinx (and MkDocs) - so people know they are there. This can only really happen by somehow exposing build.commands.
• NOT communicating this possibility will seem like we ONLY support Sphinx and MkDocs. This leads to fundamental misunderstandings of what the platform can do.

So I added a basic template with an echo command writing an index.html file.

I don't think we should remove build.commands from the how-to, but it should be easy for the user to understand that this is only relevant for a new project that needs to customize its entire build process.

Again, leaving out this part in order to prioritize making the how-to look fast or easy for Sphinx and MkDocs users is likely a disservice to ourselves. We should include build.commands in a way that isn't discouraging or confusing for Sphinx/MkDocs users, which I think we are already partly solving with the tabbed interface and the section's heading.

But I hope to hear some suggestions on improving this part!!

Edit: So one of the ways to make this look better, could be to have an example where an actual custom tool is installed and run. Like docusaurus.

Edit 2: Ah that was already @humitos's point => #10301 (comment) - yes, I think we are improving the example by showing how to install and run a real documentation tool.

Edit 3: We might have a version of the how to in the future that for instance lists Sphinx, MkDocs, Pelican and Docusaurus. And below the tabbed interface there is a link like "Don't see your favorite documentation tool here? Read our guide on setting up a configuration file for a custom documentation tool".

[benjaoming]

Update! I think this will work well:

To the point of avoiding too much complicated information about custom build commands, we hide all that in "Other tools".

We also show a proper example for a tool that's setup with custom build commands. I picked Docusarus to show that Node.js is supported.

[agjohnson]

Well, so I absolutely do want to eventually cover many tools here, or at least a subset of the tools and cover all the tools we can in the application version of this UI.

However, my opinion has not changed on build.commands, and it is confusing to point novice users towards a feature where the rest of our configuration file stops working. This feels like a timing issue: both options are still beta features and build.commands is an expert level feature. It's great that we can point users towards this solution now, but it's not something I'd point all users towards.

If we are prioritizing the override of build.jobs.build.{html,pdf,epub}, then this is okay temporarily. But otherwise, I don't think we should accumulate novice users using an advanced feature like build.commands. We don't have control of what this user is doing and they will be more likely to be lost as they are using a configuration file where they have to do everything.

[benjaoming]

However, my opinion has not changed on build.commands, and it is confusing to point novice users towards a feature where the rest of our configuration file stops working. This feels like a timing issue: both options are still beta features and build.commands is an expert level feature. It's great that we can point users towards this solution now, but it's not something I'd point all users towards.

Hi @agjohnson !

I was just pulling in the branch from another computer. After pulling it in and building, the tabs shown in the screenshot didn't show for me locally. I had to run make clean firstly to get a fresh version of the article. I'm not sure what mechanism in Sphinx that causes this, normally articles are refreshed (but TOC-indexed elements might not refresh).

The current state of the docs are supposed to eliminate expert level features, so maybe it's because you'd like a seealso to be removed or that I missed something while trying to eliminate the remnants of the previous approach?

[agjohnson]

The current state of the docs are supposed to eliminate expert level features

I still see build.commands used in two examples: Docusaurus and the custom tool example.

I am calling build.commands expert as:

• Most of the configuration file doesn't function when using build.commands
• The user is responsible for every part of the build process
• And we can't offer any control when projects use build.commands
• These features are beta still

I agree it's still helpful to point users towards an example like the Docusaurus example, but not in a guide recommended for novice users.

I would sooner drop these from the tabbed interface until we have something like build.jobs.build overrides, which would be more friendly towards novice/advanced users.

[benjaoming]

I had this in an early comment...

To give some context:

• On many occasions, I've seen it noted that we need to promote using other documentation tools than Sphinx (and MkDocs) - so people know they are there. This can only really happen by somehow exposing build.commands.
• NOT communicating this possibility will seem like we ONLY support Sphinx and MkDocs. This leads to fundamental misunderstandings of what the platform can do.

It would be great if you can suggest a way to include people who read this guide and want to use a different documentation tool 👍

I apologize in advance for potentially misunderstanding something around the prioritization of custom tools (See also: "Generalize build process patterns to support more tools"). More specifically that I thought having an easy-to-copy-paste template for Docusaurus (or another tool) aligned very very well with high-level priorities.

[agjohnson]

It would be great if you can suggest a way to include people who read this guide and want to use a different documentation tool

I'm suggesting we wait on this until the tool is somewhat supported. We already have information on unsupported tools in our build customization docs if the user chooses, but it's under a warning that build.commands is beta, might break, and our hosting features won't work ¹. It's a place where novice users are going to encounter all of the rough edges of our platform, so not a great impression.

Right now, we're solving a different problem with this page: we don't have any introductory content on our configuration file for novice users.

It's fine to keep the scope of this page to the tools we currently support. Having examples for Sphinx and Mkdocs is a 100% improvement over what we had. We'll add more as we go.

Footnotes

1. Some of our hosting features are partially working in a beta test of the addons JS, but our flyout is missing still. ↩

[benjaoming]

Alright, those guides have been removed 👍

[agjohnson]

I've moved further examples off to an issue we can remember to come back to when we're ready:
#10418

I'm merging this for now, as it's close and all feedback looks to be addressed now. Thanks for the help everyone!

[benjaoming]

Awesome, I look forward to accommodating all the new build features in future work. Thanks for explaining the position 👍

[benjaoming]

Also big thanks to @nikblanchet for the initiative 👍 It went a bit hectic at the end, but the result is super positive -- if you have any additional feedback please do add it, and we can still pick up on matters.

Minor note: We got sphinx-copybutton added, that was really nice, I've seen it play out on different documentation pages and it Just Works® :)