Error about incompatible docutils version - sphinx-design instead of sphinx-tabs?

[jugmac00]

When following the setup instructions on readme.rst, and after running make html the first time, I get the following error in my output.

ERROR: sphinx-tabs 3.4.1 has requirement docutils~=0.18.0, but you'll have docutils 0.20.1 which is incompatible.

The installation process continues and the documentation gets build, so this seems to be a minor issue.

My setup Ubuntu 20.04, Python 3.8.10

It looks like that when running make html we do not use a set of known and pinned dependencies.

In the readme.rst you can read

A complete set of pinned, known-working dependencies is included in .sphinx/pinned-requirements.txt.

There is no such file in my checkout, and from scanning the make file it also does not look that the above mentioned file gets created - at least not with that name.

[syncronize-issues-to-jira[bot]]

Thank you for reporting us your feedback!

The internal ticket has been created: https://warthogs.atlassian.net/browse/DOCPR-129.

This message was autogenerated

[s-makin]

Since we also use sphinx-design, which includes much nicer looking tabs than the sphinx tabs module, would it be worth us just removing sphinx tabs and avoiding the issue in that way? Or are they required for something specific?

[ru-fu]

In the readme.rst you can read

A complete set of pinned, known-working dependencies is included in .sphinx/pinned-requirements.txt.

Oh yes, we should get rid of that sentence - we removed the pinned-requirements.txt since it was always outdated.

The error about the incompatible versions can be ignored. I don't know why it's raised in the first place, since it never caused any issues.

Since we also use sphinx-design, which includes much nicer looking tabs than the sphinx tabs module, would it be worth us just removing sphinx tabs and avoiding the issue in that way? Or are they required for something specific?

I've never used the tabs in sphinx-design. Do they work the same way as the sphinx-tabs? So that if you have the same kind of tab on different pages (say "Windows" and "Linux") and you select the one that is relevant to you, that one is the selected one for all tab sections (also on different pages)? (See here and here for an example.)

[s-makin]

You can sync tabs with sphinx-design, yea - I've done that in the Pro Client docs.

Also, it works with both markdown and restructuredtext, which is nice. Since it includes a lot of different fancy components I find it more convenient to just use this module rather than several.

[ru-fu]

I'll test if it does what we need for LXD - in that case, I'm totally fine with dropping sphinx-tabs. (Or we could probably drop it either way, since we can always enable sphinx-tabs for LXD as a custom extension.)

However, this will need updating the cheat sheets and the style guide.

[pmatulis]

We should be careful because sphinx-tabs may be used by remote repositories that are also syncing with this current repository. That will constitute a breaking change.

[ru-fu]

I've now tested the tabs in sphinx-design a bit, and I'm reluctant to change our recommendation to use sphinx-design for tabs instead of sphinx-tabs.

The main reason is that the syncing doesn't work as well in sphinx-design. Yes, you can sync tabs within a page, but if you reload the page (or shift-reload in Firefox), you will be back at the first tab - in sphinx-tabs, once you select a tab, that's the one you will see. When you switch from one page to another, you loose your selection with sphinx-design, while sphinx-tabs retains it. Here's an example for sphinx-tabs: Select API or UI here, then navigate to "Configure instances" (two above in the navigation), and your selection remains. This is a very useful feature, because if you use only one option (CLI/API/UI, or Linux/Windows/Mac), you don't care about the others and don't want to start out by selecting the one you're interested in on every single page again.

The other reason is that we're trying to mimic Vanilla, and even if the sphinx-design tabs might look nicer, we already tweaked the sphinx-tabs ones to look the way we want.

So my suggestion is to update the style guide to make it clear that there are two options, but that we recommend to use sphinx-tabs (for the mentioned reasons). We can then move sphinx-tabs to the custom-conf.py file so it's easy to remove if teams don't want to use it. But I wouldn't want to remove it entirely, because I think this is the preferred tab style to use.

[ru-fu]

Closing this. The original issue of incompatible versions has been fixed with the latest release of sphinx-tabs, which doesn't require a specific docutils version anymore.

https://github.com/canonical/sphinx-docs-guide/pull/23 updates the style guide to allow both kinds of tabs, with an explanation on when you should prefer sphinx-tabs.

https://github.com/canonical/sphinx-docs-starter-pack/pull/177 updates the styling of both tabs to be similar and close to Vanilla.