Skip to content

Latest commit

 

History

History
70 lines (45 loc) · 2.48 KB

design.rst

File metadata and controls

70 lines (45 loc) · 2.48 KB
Raw

Designing Read the Docs

So you're thinking of contributing some of your time and design skills to Read the Docs? That's awesome. This document will lead you through a few features available to ease the process of working with Read the Doc's CSS and static assets.

To start, you should follow the installing-read-the-docs instructions to get a working copy of the Read the Docs repository locally.

Style Catalog

Once you have RTD running locally, you can open http://localhost:8000/style-catalog/ for a quick overview of the currently available styles.

image

This way you can quickly get started writing HTML -- or if you're modifying existing styles you can get a quick idea of how things will change site-wide.

Typekit Fonts

RTD uses FF Meta via TypeKit to render most display and body text.

To make this work locally, you can register a free TypeKit account and create a site profile for localhost:8000 that includes the linked font.

Readthedocs.org Changes

Styles for the primary RTD site are located in media/css directory.

These styles only affect the primary site -- not any of the generated documentation using the default RTD style.

Sphinx Template Changes

Styles for generated documentation are located in readthedocs/templates/sphinx/_static/rtd.css

Of note, projects will retain the version of that file they were last built with -- so if you're editing that file and not seeing any changes to your local built documentation, you need to rebuild your example project.

Contributing

Contributions should follow the contributing-to-read-the-docs guidelines where applicable -- ideally you'll create a pull request against the Read the Docs GitHub project from your forked repo and include a brief description of what you added / removed / changed, as well as an attached image (you can just take a screenshot and drop it into the PR creation form) of the effects of your changes.

There's not a hard browser range, but your design changes should work reasonably well across all major browsers, IE8+ -- that's not to say it needs to be pixel-perfect in older browsers! Just avoid making changes that render older browsers utterly unusable (or provide a sane fallback).