readthedocs/sphinx_rtd_theme

Add documentation on how to extend the theme

Open

#582 opened on Feb 27, 2018

View on GitHub
 (3 comments) (2 reactions) (0 assignees)CSS (3,473 stars) (1,413 forks)batch import
Good First IssueNeeded: documentation

Description

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

Contributor guide

Tech stack
pythoncsshtmljavascript
Domain
documentationfrontend
Issue type
documentation
DifficultyEstimated implementation difficulty for a new contributor, from 1 for very small changes to 5 for expert-level work.
3
Estimated timeA rough time range for an experienced contributor to investigate, implement, test, and prepare a pull request.
half day
Activity statusHow available the issue appears right now: fresh, active, stale, blocked, or waiting on maintainer input.
stale
ClarityHow clearly the issue explains the expected change, acceptance criteria, and next step.
clear
Prerequisites
Sphinx basicsCSS/HTMLPython
Newbie friendlinessA 1-100 score estimating how approachable this issue is for first-time contributors.
70
Research direction
Review the theme's ` init .py` for the `setup()` function and how `app.add stylesheet()` is used. Examine the template files in `sphinx rtd theme/`, particularly `layout.html`, to understand the template block structure. Compare with Sphinx's default template blocks. The issue comments may provide additional context on what users commonly ask.