readthedocs - table formatting under 1.1

[keiranmraine]

The formatting under 1.1 has changed quite dramatically for the readthedocs option. Is this intentional?

Table from 1.0.4:

Table from 1.1:

My mkdocs.yml (variables expanded in bash script):

site_name: CI reports - $CI_PROJECT_PATH
repo_url: $CI_PROJECT_URL
repo_name: GitLab
edit_uri: null
site_description: CI reports for $CI_PROJECT_PATH
theme:
     name: readthedocs
nav:
$NAV

[waylan]

What is the behavior of the upstream Sphinx theme?

If the new behavior match upstream, then this is an intentional change. The MkDocs theme should not include anything which is not supported upstream. However, if this is a regression from the upstream Sphinx theme we may need to add some additional rules to theme_extra.css. A PR is welcome.

[keiranmraine]

The sphinx theme stable demo shows the tables to have the clean formatting (as desired):

https://sphinx-rtd-theme.readthedocs.io/en/stable/demo/lists_tables.html#option-lists

[waylan]

Thanks for the link. Sure enough we have a problem with table formatting. The way this works is that we provide the upstream CSS in theme.css. That file comes directly from upstream without modification. We then have a few fixes specific to MkDocs in theme_extra.css. However, the few rules in theme_extra.css have not changed between versions 1.04 and 1.1. What has changed is that theme.css was updated to a more current version from upstream. Doing a little spelunking with the inspector, it appears that all style rules for tables in theme.css are applied to .rst-content table.docutils whereas previously they simply used .rst-content table. Of course, Markdown does not assign a docutils class to tables so the rules are being ignored.

Presumably, a fix for this would be to copy all relevant rules from theme.css to theme_extra.css and alter them to be applied to .rst-content table. Under no circumstances should we edit theme.css directly. A PR is always welcome.

[waylan]

As an aside, the inconsistency in the code spans depicted in the screenshots above was addressed in #2029. This would be a similar type of fix.

[mattbrictson]

Doing a little spelunking with the inspector, it appears that all style rules for tables in theme.css are applied to .rst-content table.docutils whereas previously they simply used .rst-content table. Of course, Markdown does not assign a docutils class to tables so the rules are being ignored.

I don't think this is an issue with the CSS changing. The upstream table CSS has required the docutils class for quite some time. The problem is that mkdocs used to use JS to apply the docutils class to tables (see #257) but that was clobbered when the JS file was entirely deleted in 873b970#diff-be6164876d7aedfd5a20eab74b55c16d.

Was the removal of theme.js intentional? If so, could we bring back just the part of it that ensures table styles work? I.e.

$('table').addClass('docutils');

[mattbrictson]

I fixed this for my own site by adding the following:

extra_javascript:
  - js/extra.js

// js/extra.js

document.addEventListener("DOMContentLoaded", function() {
  document.querySelectorAll("table").forEach(function(table) {
    table.classList.add("docutils");
  });
});

[waylan]

Was the removal of theme.js intentional?

Technically it wasn't removed. rather it was replaced with the upstream JavaScript. However, looking at it now, it appears that the previous version included both some of the upstream code and some hacks to make it work with MkDocs. Perhaps we need to bring parts of the old hacks back. If course, that should happen in a separate file. The upstream file should remain unmodified from upstream.

[rockandska]

Hi

Table decoration is not the only thing who has changed, text surrounded by single quote too

In 1.0.4

In 1.1.0

Regards

[wodny]

@rockandska As already mentioned, see #2029.