#267 Name conflict for CSS class container

[viz]

The hardcoded generic CSS class "container" may conflict with classes defined in other stylesheets. This happens, for example, when using Sphinx Bootstrap theme (https://github.com/ryan-roemer/sphinx-bootstrap-theme) which combines the popular Bootstrap framework with Sphinx.

Here's a small example reproducing the problem.

test.rst:

This is a test.

.. container::

  Text inside a container.

template.txt:

%(head_prefix)s
%(head)s
%(stylesheet)s
<link rel="stylesheet" href="https://cdn.jsdelivr.net/bootstrap/3.3.0/css/bootstrap.min.css">
%(body_prefix)s
%(body_pre_docinfo)s
%(docinfo)s
%(body)s
<script src="https://ajax.googleapis.com/ajax/libs/jquery/1.11.1/jquery.min.js"></script>
<script src="https://cdn.jsdelivr.net/bootstrap/3.3.0/js/bootstrap.min.js"></script>
%(body_suffix)s

Running the command

rst2html --template=template.txt test.rst test.html

results in the HTML that looks as follows:

As you can see "Text within container" has weird formatting.

Because "container" is a common name used in other frameworks such as Bootstrap, I think it would be better to prefix it in Docutils to avoid name conflicts, for example, use "docutils-container" or at least have an option to do so.

[Günter Milde]

I agree, that the class name may be unfortunate. However, changing it now produces backwards incompatibilities which is worse.

The "container" directive is intended for use with a specific class attribute and a custom style sheet. Then, it is easy to create CSS roles
that override the generic "container", e.g.

.container.classargument: {margin: 0em; color: red}

[viz]

Unfortunately adding a class attribute doesn't solve the problem with Bootstrap, because its CSS applies to the container class regardless of any additional classes. Overriding all Bootstrap's container styles is rather impractical.

Would it be possible to add an option to rename "container" class to something else? This option can be turned off by default to ensure backward compatibility, but turned on by projects such as Sphinx Bootstrap where the conflict occurs.

[Günter Milde]

I hesitate to add configuration options for special cases.

It would, however, be simple and backwards compatible to add the "docutils" class value to every "container" div. This would make it possible to solve the problem with specific CSS rules without the need for an additional class value in the rst source.

I don't see much styling to overwrite: to reverse the formatting done in
bootstrap.css, it should suffice to include the CSS rules

.container.docutils,
{
  width: inherit;
}

.container.docutils:before,
.container.docutils:after {
  display: none;
  clear: none;
}

in a custom style sheet (needed anyway if you want to do something with the "container"

).

This should work with the current version if you add the "docutils" class value in the source::

.. container:: docutils

  Text inside a container.

[viz]

Thank you for the suggestion and sorry for a slow reply.

I tried the workaround you suggested and it seems to work. My only concern is that this workaround can be easily broken by changes to Bootstrap because it basically tries to undo Bootstrap styles instead of keeping Docutils styles in a separate "namespace".

Anyway, if there is no backward compatible way to address this, I guess I'll have to live with it or seek some other options. Unfortunately Boostrap devs are equally unwilling to introduce a prefix for CSS classes.

[Günter Milde]

Added the "docutils" class value, so that a CSS rule specific to docutils.container can overrule Bootstrap-styling.