Add documentation on how to extend the theme

agjohnson commented 6 years ago

This is something that I get questions on a lot:

New maintainers want to know how to add CSS/JS. We prescribe adding in a setup() extension point via app.add_stylesheet() to get around our extension
Companies doing a deeper conversion of our theme to match their brand should know how to extend our templates
Our template blocks should be documented some? Or at least we point to the Sphinx default list of blocks that we emulate

tuukkamustonen commented 6 years ago

I've been doing some minor CSS adjustments/fixes on top of the theme. It's not something I've really had time for, so I just hurried in something like:

In conf.py:

html_style = 'override.css'

And override.css:

@import url("css/theme.css");

#table-of-contents {
    background-color: #e3e3e3;
    border: 1px solid #c9c9c9;
    padding: 20px;
    margin-bottom: 20px;
}

Seems pretty straightforward. However, when you get deeper in, it gets messy and complicated:

/* Less whitespace after highlight blocks in lists, same as for <p> (bundled) */
.rst-content .section ol div[class^="highlight-"], .rst-content .section ul div[class^="highlight-"] {
    margin-bottom: 12px;  /* default: 24px */
}

Or even:

/* Margin after <ol> within lists */
.wy-plain-list-decimal li ul, .rst-content .section ol li ul, .rst-content ol.arabic li ul, article ol li ul {
    margin-bottom: 12px;  /* default: 0 */
}
.wy-plain-list-disc li ul, .rst-content .section ul li ul, .rst-content .toctree-wrapper ul li ul, article ul li ul,
.wy-plain-list-disc li ol, .rst-content .section ol li ol, .rst-content .toctree-wrapper ol li ol, article ol li ol,
.rst-content .section ol li ul, .rst-content .toctree-wrapper ol li ul, article ol li ul,
.rst-content .section ul li ol, .rst-content .toctree-wrapper ul li ol, article ul li ol {
    margin-top: 12px;  /* default: 0 */
    margin-bottom: 12px;  /* default: 0 */
}

I'm not sure what the latter even does anymore, or how I ended up having exactly those selectors. I guess I copied something from the bundled theme.css and override properties.

Something more format/documented/simpler, be it an actual extended theme, or just quick CSS override like here, would definitively be nice.

stsewd commented 3 years ago

We should also document hmlt_context https://github.com/readthedocs/sphinx_rtd_theme/issues/156

humitos commented 1 month ago

I'd not write specific documentation for this, but just link people to the official docs:

readthedocs / sphinx_rtd_theme

Add documentation on how to extend the theme #582