Add list of supported tools

[plaindocs]

And also addon config for each one.

Fixes #11187

Still to do:

• delete Getting started with * content
• redirect user/intro/getting-started-with-mkdocs.rst -> user/intro/mkdocs
• redirect user/intro/getting-started-with-sphinx.rst -> user/intro/sphinx
• figure out example repos
• revert dependencies

Open questions:

• we probably need to address the distinction between people using mkdocs in the RTD config, and people using mkdocs in build commands on this page. And go back to the working here https://docs.readthedocs.io/en/stable/addons.html#enabling-read-the-docs-addons )are you already using the addons, or are the addons already usable if you've configured them)

---

📚 Documentation previews 📚

• User's documentation (docs): https://docs--11547.org.readthedocs.build/en/11547/intro/doctools.html

[humitos]

I think this is going in the correct direction.

I left a suggestion about the section structure for the addons that I think it works better.

Apart from that, there are just other small suggestions to link to external and internal pages.

Let me know if you have any particular doubt where I can be useful.

[plaindocs]

@humitos how general is the advice to pin your Sphinx version? Should we be recommending this for all doctools?

   We strongly recommend to :doc:`pin the Sphinx version </guides/reproducible-builds>`
   used for your project to build the docs to avoid potential future incompatibilities.

[humitos]

@humitos how general is the advice to pin your Sphinx version? Should we be recommending this for all doctools?

It's good advice. However, I don't think we need to cover this into these introduction pages. It will deviate the attention to a completely different and deep hole.

[agjohnson]

The subpage structure seems plenty good, we can always build out more content on the listing page later but I did note it for now.

[plaindocs]

I can easily revert c7216e9 if we'd prefer a different approach.

[plaindocs]

At a guess I need to do the pip-compile --output-file=requirements/docs.txt requirements/docs.in when adding dependencies to docs.in?

[humitos]

At a guess I need to do the pip-compile --output-file=requirements/docs.txt requirements/docs.in when adding dependencies to docs.in?

Yes 😄

[humitos]

Looks good to me. I'm happy to merge it so we have something to link our users to. We can make iterative changes if needed.

[humitos]

We've change how this works now implementing the version/language selectors and that's what we want people to use for now. They are enabled by default, so we should remove this section since it's not valid anymore.

The new version of the theme hides the integrated flyout by default. If the user want to enable it, they have to define flyout_display: "attached". If we want to keep this section, we could communicate that instead.

[humitos]

I went ahead and commented this section for now in eb71007; but we need to revisit this.

[plaindocs]

Hey @humitos , let me see if I've got this right:

• version / language selectors are enabled by default (are they different from the new flyout?) - are they configurable?
• The flyout is hidden by default, to show it use flyout_display: "attached"

[humitos]

version / language selectors are enabled by default?

Yes, only on our own theme, tho.

(are they different from the new flyout?)?

Yes and no. They use the exact same data (same versions, languages, etc). However, the version/language selectors shown in the top left nav bar are managed by the theme itself.

On the other hand, the new flyout is automatically injected by Read the Docs and is shown floating a the bottom.

are they configurable?

The version/language selectors are not configurable. The flyout is configurable via the Addons' settings in the dashboard.

--> actually they are configurable by the theme?

The flyout is hidden by default, to show it use flyout_display: "attached"

No. The new flyout (the one that Read the Docs injects) is shown by default (together with the version/language selectors from the theme).

If flyout_display is defined as attached in the theme options, the "integrated flyout" will be shown in at the bottom of the navbar. However, this does nothing on the new Read the Docs Addons flyout. At this point, both flyout will be shown.

The Read the Docs Addons flyout can be disabled from the Addons' settings in the dashboard.

---

Does this make sense?

--> only kinda at the moment

[plaindocs]

Let me try to poke at things and see if it does :-D

[humitos]

we probably need to address the distinction between people using mkdocs in the RTD config, and people using mkdocs in build commands on this page

What is this distinction you refer to here?

[humitos]

I made some small changes to this PR so we can merge it now and making it part of tomorrow's release. However, there are a few things to work on still. I want to make those changes in an iterative way so we can start linking this content to users and testing how it performs.

[plaindocs]

we probably need to address the distinction between people using mkdocs in the RTD config, and people using mkdocs in build commands on this page

What is this distinction you refer to here?

So you could (in theory) build mkdocs docs like https://docs.readthedocs.io/en/stable/config-file/v2.html#build-commands or with https://docs.readthedocs.io/en/stable/config-file/v2.html#mkdocs right?

But would there be any config difference?