Mark commercial documentation more clearly

[astrojuanlu]

How do we distinguish .com content? Perhaps an emoji and a warning at the top of the guide or similar to what we do for sphinx-only content?

I was precisely thinking of an emoji. And rather than a warning, a custom-colored admonition?

Creating a custom admonition was harder than expected 🙃 But even so, I think the right approach would be to mark a page or a section with :commercial:, and have some extension code that does the rest (changing the color? adding an admonition on top? adding an emoji to the title?). Also, it should work on PDF and EPUB, not only on HTML.

[ericholscher]

I don't think we need an extension for this. I think we can just use an emoji and a normal admonition at the top of the page?

[astrojuanlu]

Yes we can - but we'd have to do it manually for every page? A bit of copy-paste that we could avoid with some Sphinx hackery

^{See also XKCD#1205, or XKCD#1319...}

[ericholscher]

We'd still need to set some metadata on every page, and probably want different admonitions I'm guessing over time :)

I don't think this is a problem that needs a solution other than writing content.

[humitos]

If we want to do an extension, it can be done in a similar way as https://github.com/humitos/sphinx-version-warning . It used to add an extra docutils node for the admonition.

While using an extension like that may be simple, I think it may be too much for this. I think we can just add a CSS class to do this job:

.. admonition: Title
   :class: commercial
   
   Content

Then in a CSS file:

.commercial {
  ...
}

An improved version of this could be to use :commercial: RST metadata on each page. Then from Python at build time, iterate over those and append an admonition node on the top of the page. It's simpler, but does not allow different admonitions for each page.

[astrojuanlu]

I concede that creating an extension for this might be premature optimization, but do we really want different admonitions for each page? I think we should strive for consistency.

Even if we don't block this work on creating an extension, I don't think this use case is so niche. I bet other projects would benefit from it.

[humitos]

I think that depends on what we want. With more clear requirements on the work wanted here, it would be easier to give better feedback here. A Sphinx extension can be "as simple as a Python function" ™️ in our conf.py if we want to just add a docutils node on the top --so I'm not discarding that idea yet (see https://github.com/humitos/sphinx-version-warning/blob/0.2.0/versionwarning/__init__.py#L39 and https://github.com/humitos/sphinx-version-warning/blob/0.2.0/versionwarning/signals.py#L18-L21 which are, 10 lines?)

[astrojuanlu]

A Sphinx extension can be "as simple as a Python function" ™️ in our conf.py if we want to just add a docutils node on the top

Hah, not so fast 😛 sphinx-doc/sphinx#6751 (it just needs to be in doc_extensions.py)

[agjohnson]

I'm all for simple solutions until we have a strong need for more creative solutions. If we are going to put the same block at the top of pages/sections that are specific to commercial hosting, we can always just start with an .. include::.

A complementary (or I might say underlying, even) issue we have with commercial-specific documentation is that this documentation is scattered and rather buried. Much of the current content is either in guides, or under a Read the Docs for Business section, at the bottom of our TOC and the bottom of our front page of our documentation, barely above "Legal Documents" 🙃

If I was looking for information on a commercial-specific feature, I would expect it to be under "Features" -- not "Advanced Features" or "RTD for business". I think this change alone would preempt a special classification for commercial hosting pages, though I could see this being really helpful metadata to have in our TOC.

Anyways, this could all very well require an admonition still, so maybe this is a good indicator to start small. We can always come back to this and get fancy if we don't feel reorganizing clarified enough.

[humitos]

I'm all for simple solutions until we have a strong need for more creative solutions. If we are going to put the same block at the top of pages/sections that are specific to commercial hosting, we can always just start with an .. include::.

This is the solution that's currently implemented:

readthedocs.org/docs/user/guides/manage-read-the-docs-teams.rst

Line 4 in 3eae8f5

.. include:: /shared/admonition-rtd-business.rst

A complementary (or I might say underlying, even) issue we have with commercial-specific documentation is that this documentation is scattered and rather buried

This was part of the Diataxis work we've done.