docs/conf.py says:

Note: Our strategy for intersphinx mappings is to have the upstream build location as the
canonical source and then cached copies of the mapping stored locally in case someone is building
when disconnected from the internet. We then have a script to update the cached copies.

What script does that?

I have a plan to make a new theme based on Furo or its siblings. It'll be responsive, accessible, and support dark mode. It's currently impossible to just inherit Furo but there's a lot of improvements happening in the Sphinx ecosystem that will have a great impact on our ability to make modern themes.
One of the developments is tracked here python/docs-community#1 (comment).
P.S. This will probably need to happen in a new repo but until then, I'll keep the issue here.

Search incorrectly uses Ansible search, which is not desired for standalone projects like molecule or ansible-lint.

I discovered that our theme breaks with sphinx_rtd_theme==1.0.0 and I had to pin it down until I discover what caused that.

We currently have no version bounds on this package, so we should add one.

The search and version selection scrolls with the left side bar. Unfortunately this results in some pages showing no search or version selection on initial page load, and with no visible indication that it even exists.

Example: https://docs.ansible.com/ansible-core/2.14/dev_guide/testing/sanity/integration-aliases.html

Here's what the initial page load looks like under Firefox on macOS.

The version selection and search box should always be visible, regardless of the scroll position of the navigation or content.

When browsing with lynx to https://sphinx-ansible-theme.readthedocs.io/en/latest/, it complains about "Broken HTML". This turns out to be Lynx expecting <select> to be inside a <form>, which I do think is not required by HTML 5 (https://html.spec.whatwg.org/multipage/form-elements.html#the-select-element, https://html.spec.whatwg.org/multipage/form-control-infrastructure.html#form-owner, https://html.spec.whatwg.org/multipage/forms.html#form-associated-element).

Making Lynx happy isn't too hard, we'd basically need a dummy <form> around the select element.

(Ref: ansible/ansible#76759 (comment))

Based on the Documentation working group meeting, we would like to investigate the option to add expand/collapse capability to the Ansible theme.

This is still an idea we need to flesh out some more, but the hope is that we can start creating Ansible example pages where we have multiple components to each example. At the minimum, a playbook and the associated output. Then the user could click on the title of an example that sounds interesting and 'expand' to see the example. This would make it potentially easier when scrolling through large example pages to find what's of interests without having to scroll past long coding or output sections that aren't of interest.

If this is possible, we could then expand the functionality to the module docs pages as well.

Other projects are likely to have different versions than Ansible but we all want to default to "latest" as default but also to display few older versions.

We no no want to display patch versions only X.Y versions.

Click the top-left logo and get a 404: https://ansible-collections.github.io/community.dns/branch/main/

Click the top-left logo and it points to the index: https://ansible-sdk.readthedocs.io/en/latest/

In order to make the search functionality work across sites hosting Ansible documentation we need to few extra domains to be added to https://app.swiftype.com :

• https://sphinx-ansible-theme.readthedocs.io <-- ready (try search on it)
• https://molecule.readthedocs.io - wip
• https://ansible-lint.readthedocs.io - wip

At this moment the search returns only results from docs.ansible.com rendering in-site search useless.

We are unlikely to want to limit the search to a single project. Also the fact that swifttype does not have a free plan forces us to seek a single search engine implementation.

Right now, GitHub says the latest release is 0.3.2 (from July 2020), while the latest actual release is 0.7.0 (from yesterday). I think it would be helpful if GitHub releases would be created for the release tags. This also makes it possible to subscribe to releases from this repository and actually be informed when there's a release :)

the theme currently has the following parts that are (IMHO) specific to docs.ansible.com:

• the globalnav in ansible_extrabody.html (ansiblefest etc)
• JS for trackers from Google and Red Hat

if the theme is supposed to be usable outside of the docs.ansible.com site, it'd be cool if users could disable these.

I discovered (while working on ansible/ansible#74318) that this is not the case for the configurable settings that we specify in theme.conf (and are overridable via html_theme_options).

The workaround is to supply those vars via html_context but then it's pointless to have them in theme.conf so this has to be fixed.

Ref: https://stackoverflow.com/a/33845358/595220

When extracting the theme, @ssbarnea dropped in MIT license into the project metadata.
This suggests that the derivative work should be GPLv3-compatible (since it comes from ansible/ansible where the majority of the repo content is GPLv3).

@abadger @acozine @gundalow does this sound right?

Currently most community projects have their own websites, likely using RTD and their own themes.

The only exception I am aware of is ansible-lint which is nicely hosted under docs.ansible.com but the publishing process went broken and remained broken for more than an year. Mainly the project docs are out of sync with the project itself.

As I am aware of the sensitivity regarding what gets published to docs.ansible.com, I can understand that Ansible core team wants to assure that goes there is properly vetted. This is a bit of a conflict with the needs of the community projects, which may need or want to release docs at their own cadence, and more important not to depend on others regarding doc publishing.

A: subfolder under docs.ansible.com

• maximum visibility
• easy search (make use of same search engine)
• cannot use RTD build process as we would need our internal publishing job to update production

B: subdomain like community.ansible.com

• good visibility, makes it clearly visible it is community driven
• still indexable and we could make results visible from docs searches
• we can make use of RTD subproject feature
• can use RTD custom domain feature to host all community docs, even disable advertising, with minor costs. If we decide to go DIY we can do it without affecting the user-experience
• Using RTD brings serious benefits, like being able to preview the pull-request builded docs, making much easier to review changes made to them.

C: each project with its own site (current)

• no search across projects
• much harder to distinguish between projects under community umbrella and random projects from internet
• documentation theming will obviously differ a lot between projects, affecting now only browsing but also maintenance
• prevents us from analizing how community documentation is displayed, consumed or to make more holistic improvements.

While advertising Tower is ok for Ansible itself, I do find it bit annoying for other projects, and I would prefer o have none for them.

First reported in ansible/ansible#77714 and moved here:

Summary

Some links on docs.ansible.com are unclickable. I think it is specific to this combination:

• The documentation of an option has a link
• The link is near the bottom of the option
• It isn't the last option
• Browser size is less than 1200px wide (mine is ~1040)

I encountered this on https://docs.ansible.com/ansible/latest/collections/community/docker/docker_prune_module.html (specifically containers_filters, images_filters and networks_filters, but not volumes_filters), but since the CSS applies to everything, I'm reporting it here.

(ignore that the link is purple in the screenshot, I opened it from the inspector)

Trying to inspect the link actually gives you the div class="ansibleOptionAnchor" of the next option, which is probably why on that page it works for volume_filters.

Looking further into it, it also makes text near the bottom of any item (except the last item) unselectable; the cursor remains a pointer instead of turning into a caret.

There are multiple CSS min/max width statements going on, also on elements higher up in the tree (especially the td). Involved CSS files appear to be (at least) https://docs.ansible.com/ansible/latest/_static/css/ansible.css and https://docs.ansible.com/ansible/latest/_static/antsibull-minimal.css but I have no idea where those are coming from.

Issue Type

Documentation Report

Component Name

CSS

Ansible Version

$ ansible --version

Configuration

$ ansible-config dump --only-changed

OS / Environment

Firefox 99.0.1 on Archlinux

Additional Information

It improves the user experience.

(feel free to edit the title and/or move this to the relevant repository)

Code of Conduct

• I agree to follow the Ansible Code of Conduct

Summary

table overlaps text on some pages. See Contributing to Ansible-maintained Collections page, screenshot below.

This is a blocker for ansible/ansible#74318.

Today I learned - if we use :envvar: for environment variables, they are hotlinked on docs.ansible.com. See https://docs.ansible.com/ansible/latest/reference_appendices/config.html#action-warnings for an example.

The output unfortunately doesn't give the reader a hint that this is a hotlink. Maybe if we changed the text to blue it might help?

Ref: ansible/ansible#70849.

I'm thinking about integrating https://sphinx-version-warning.readthedocs.io and using VERSION in conf.py for checking what banner to use.