Docs: create a page per doctool supported

[humitos]

trafficstars

We ended up wanting to expose examples to our users simpler and easy to maintain than our "Example projects" (https://docs.readthedocs.io/en/stable/examples.html) and better and more user-friendly and production-ready than our test-builds project (https://test-builds.readthedocs.io/en/latest/).

I think that something in-between those would work pretty well in our documentation. I imagine a page per doctool with:

• one paragraph with the introduction to the doctool and link to the official website
• a YAML configuration file example
• a link to a live documentation example from a specific test-builds branch (e.g. https://test-builds.readthedocs.io/en/docsify/)
• explanation of the arguments passed to the command if there are something special for Read the Docs
• extra resources (themes, tutorials, etc)

In fact, I'd like to see something like this section https://docs.readthedocs.io/en/stable/build-customization.html#build-commands-examples but with a little more explanation and following the template proposed previously.

Summarizing, it seems we have 60% of the work done already but we just need to standardize it 👍🏼

Reference:

• https://github.com/readthedocs/website/pull/268#issuecomment-1977075341
• https://github.com/readthedocs/website/pull/263#issuecomment-1952399024

[stsewd]

a link to a live documentation example from a specific test-builds branch (e.g. https://test-builds.readthedocs.io/en/docsify/)

We should probably use https://github.com/readthedocs-examples instead of test-builds.

[agjohnson]

I had a similar question and these were the repos that I was thinking of. We did a fair amount of work to standardize these so seems useful to continue. I wouldn't mind if the repos were a little bit lighter weight though, I don't see us being too proactive on keeping the content there up to date.

[humitos]

I want to be sure we are all in the same page here 📄

From my proposal, the only change you would do is "use a readthedocs-examples/doctools repository with a branch per doctool" instead of using test-builds. Is that correct?

Also, I want to double check we don't want to create such big examples like https://github.com/readthedocs-examples/example-sphinx-basic/ since they are hard to bootstrap initially and also hard to maintain. Am I correct?

[stsewd]

I was thinking more of a repo per example. Maybe @ericholscher knows if there was a conversation/decision on why we are using one repo per example.

[ericholscher]

My biggest goal here is Marketing & SEO. We should have a page that shows up in search results when I search "$tool docs hosting" or similar.

I don't think many people are actually using our example projects, so I don't want the goal here to be "help people get started with $tool on RTD", but more "let people know RTD supports $tool". If we can work to build content that also helps people get started, that's great, but I want to promote that we support the tool more than build educational material at this stage.

I think we should mostly be aiming for the simplest possible examples, and perhaps even just writing documentation pages to start that mention the tool, without actually building a working example even. If there's a user using the tool, we should likely be pointing there, instead of building toy examples. Marketing is most effective if we have users that we can point to versus something we built that doesn't really show how the tool will feel to use on RTD.

[agjohnson]

It sounds like there are two (related) projects here.

I agree on the marketing focus here. I would say this feels like a good fit for website content -- showing that we support these tools and focusing on traffic flow there. Simple examples work well here, where we can. Pointing out to customers to show the examples of output works really well for this content.

But I do also agree with @humitos that showing how to support the tool is important. This feels like the issue here and is a good fit for documentation. There is a lot of overlap though.

We will want to follow up "we support 11ty" with a working example. Users will have a hard to getting to a solution on their own otherwise. There are some tools that need more help to work with RTD, but most can be pretty simple.

If we need to re-evaluate the pattern for example projects, I am fine having this conversation too. I agree the example projects repos are heavy and hard to maintain, but for now these examples are the standard.

---

So, I agree with the marketing focus. But I would say we start with high-level, lightweight content at the website promoting the tools. We can use the feedback there to prioritize examples users care about. Documentation feels like a good fit for the actionable work instead.

[plaindocs]

Hey folks, chiming in on this after the chat last week and reading up :arrow_up: .

Without looking, I expect that docs pages have a higher search engine ranking than the marketing site, and as such there is some value in adding the tools to both, with a slightly different slant:

• marketing site, so at the very least you can go and get a list of tools RTD does work with
• docs site, minimal content (which lets you start to count visits to the pages) on using tool x with RTD

I don't think many people are actually using our example projects, so I don't want the goal here to be "help people get started with $tool on RTD", but more "let people know RTD supports $tool". If we can work to build content that also helps people get started, that's great, but I want to promote that we support the tool more than build educational material at this stage.

I think the angle is more "what is the smallest config needed to get it working", after which you want to funnel folks into the standard "how do I x" flow.

So, comparing to the current mkdocs content get rid of most of that, and tell folks who are already using mkdocs how to use it on RTD, instead of telling them how to use mkdocs.

[ericholscher]

@plaindocs Yep, I think that's a great approach. We have a bunch of these minimal configs in random test-builds repos, which is probably a good starting point:

https://github.com/readthedocs/web/branches/active

For example:

• Jekyll: https://github.com/readthedocs/web/blob/jekyll/.readthedocs.yaml
• Rendered: https://test-builds.readthedocs.io/en/jekyll/

These probably need a bit of cleanup, and show some rough edges on our features given the CANONICAL_URL hacking these in the config :)

[humitos]

I wrote a comment about how to integrate the Read the Docs Addons with Material for MkDocs in https://github.com/readthedocs/meta/issues/85#issuecomment-2069254429. We should use the content from that comment to write this page.

[plaindocs]

If we've got a structure that looks a bit like

• Doc tools
  • Sphinx
  • MkDocs
  • ...

It probably makes sense to document the add-ons generically and add a section to each Doc tools page about the specifics of the integration. Something like

• Doc tools
  • Sphinx
    • Addons
  • MkDocs
    • Addons
  • ...
• RTD Addons
  • Search
  • Versions

Does that sound like it makes sense?

[humitos]

It probably makes sense to document the add-ons generically and add a section to each Doc tools page about the specifics of the integration Does that sound like it makes sense?

Yes. It makes sense to me 👍🏼

Let me know if you need any help on the technical details or more examples for doctools that we support. We have a bunch of branches on the test-builds repository with examples that I can link you to. Some of them may need an update/polish with the latest Read the Docs changes.

[ericholscher]

Just a note that jsdoc would be a good one, closing #9247 as a dupe.

[plaindocs]

Yep, need to get this ball rolling.

[humitos]

I'd like to start moving forward with these pages. Ideally, I'd love to have Sphinx and MkDocs pages written down before October 7th, which is when addons is going to be enabled by default.

Let me know if you need any help to start with this work or the scope/content of it is not 100% clear.

[plaindocs]

Thanks @humitos , I've got some extra time reserved next week to get this moving.

[plaindocs]

OK, let's do this. Gathering up the historical artefacts and threads, we're looking at two separate things here (which at some point I lost track of):

1. A new listing page of supported tools (with the description, YAML, example link), minimal stuff.
   • We don't already have separate minimal examples in https://github.com/readthedocs-examples right?
     • @humitos would you mind throwing together a few minimal config examples, or adding them to that repo?
2. And addendum to that about integrating the addons a la https://github.com/readthedocs/meta/issues/85#issuecomment-2069254429

I'm pushing up some far from finished noodling along these lines, but I'm running into some questions:

• Aren't some of these addon tweaks going to break things locally? Do we need to cover this?
• The example we have is mkdocs-material - do we want to do this specifically? Or just core mkdocs as well?
• Can we agree on a definitive list of tools we want to cover in pass 1?
  • mkdocs
  • sphinx
  • jsdoc
  • anything else?

[ericholscher]

The examples are mostly here: https://docs.readthedocs.io/en/stable/build-customization.html#build-commands-examples and in the test-builds repo for a linkable example.

[plaindocs]

Ahah, yeah, I'd not seen the full list in that repo.

[humitos]

@plaindocs to me, what you are describing as 1) and 2) are the exact same pages. In my head, this means: a new listing page of supported tools that links to individual pages for each documentation tool containing description, YAML, example link and a more technical section about specific integration/customization with Read the Docs.

Aren't some of these addon tweaks going to break things locally? Do we need to cover this?

They shouldn't break. Depending on the documentation tool, we would add something like if os.environ.get("READTHEDOCS") == "True" to define specific Read the Docs configurations. You can leave those technical sections with a placeholder for the code configuration and ping me to complete them with the exact code required. I'm happy to write that code.

The example we have is mkdocs-material - do we want to do this specifically? Or just core mkdocs as well?

That particular example should probably work on both, but I will need to double check that. We can start with Material for MkDocs for now (since it's where we tested it) and re-write the page to make it more generic later or create a new page for MkDocs in the future.

Can we agree on a definitive list of tools we want to cover in pass 1?

Sphinx and Material for MkDocs only for now. Once we have those written, we can create more, but I think we need a good structure defined first. If we have that, I think we will be able to copy&paste and adapt the content for other frameworks.

Just a reference, we have a list of documentation tools and themes were we regularly test our addons integration at: https://readthedocs-addons.readthedocs.io/. We can grab more of them from there as we move forward with this work.

Also, note that jsdoc is just a Sphinx extension, not a documentation tool. I think Eric just got confused on his comment. Writing a guide for that is out of the scope of this work and can be done in another bunch of work.

[ericholscher]

I'm fine just starting with Sphinx and Mkdocs, since I do think the structure is the main work here and should be easy to copy for other tools once we have it.

Jsdoc is definitely a documentation tool :) It's similar to Javadoc and other tools like that.

My thinking is that it's just a baseline api doc generator, and since we support specific node versions should be pretty easy to document how to use it.

https://github.com/jsdoc/jsdoc

[agjohnson]

While JSDoc is a indeed a standalone doctool, it's not actually common to see sites generated with JSDoc. It's used most commonly for lightweight type declaration and type checking more than it is for generated output.

JSDoc is quite nice paired with sphinx-js, which is a post I wanted to write a while ago. But, this is not a common configuration either.

I would skip JSDoc for a first pass on doc tools because of this. At some point it would be nice to cover, but I'd rather we pick a stronger and more widely used engine.

I agree on Sphinx/Mkdocs suggestions. Docusaurus is far more common than JSDoc and could be a good option for this or next iteration on supported doc tool documentation pages.