Repository files navigation

This repository contains the site content and static assets used to build theRead the Docs website. You can view this site athttps://about.readthedocs.com

This repository includes:

A Pelican project for our site content

This includes our site content as well as our blog.

A Pelican theme and series of templates

The Pelican configuration uses the themereadthedocs_theme, whichextends the Pelicansimple theme underneath by default. Webpack buildsassets directly into the theme path.

A Semantic UI theme specifically for marketing content

This should mostly be a stock experience, but with some customization formarketing content.

This package uses [uv](https://github.com/astral-sh/uv) to manage Python dependencies and CSS and JS assets arebuilt using a number of Node dependencies.

You will need the following requirements:

• Node.js version14
• Python version3.10 (any release>=3.6 works)
• uv (Useasdf or seehttps://github.com/astral-sh/uv for installation instructions)

Usingasdf is recommended but optional. Theasdf commands below willinstall all system level dependencies for you.

$cp .tool-versions-example .tool-versions$asdf install$asdf reshim

With the correct system dependencies configured, either withasdf ormanually, you can install all package level dependencies with:

$uv sync$npm install

Webpack handles all of the building of assets, running the development webserver, and hot reload for the site CSS, JavaScript, Pelican templates, andPelican content. This is the best way to make change to this repository.

All you need to execute locally is:

$npm run dev

This will start an auto reloading web server. You can view the built site at:

http://localhost:8080/

Any changes to the theme static assets, page/post Markdown source, or our themetemplates will reload the page in the browser. Alternatively, typers<Enter>in the Nodemon process to force a Pelican build.

If you run into issues building CSS or JS, you can work around this temporarilyby running Pelican directly and viewing the output locally:

$npm run build-html$firefox output/index.html

You will lose out on all of the nice features of Webpack this way, so it isrecommneded to use the standard development flow instead.

For every pull request, assets need to be rebuilt, or the pull request checkwill fail.

To generate production CSS and JavaScript assets:

$npm run build

This will create all of the necessary files inreadthedocs_theme/static/, aswell as regenerate all of the site content through Pelican.

Similar to other front end projects, and our Python code, we use automaticlinting and formatting for styling code to a unified format. For CSS/JS, we useprettier, which is opinionated but mostly makes good code style choices.

Linting is required for every pull request, skipping this step can cause thebuild to fail if your formatting doesn't match the intended output fromprettier.

To run linting checks, which will only report errors:

$npm run lint

To automatically format code:

$npm run format

Pages should be saved undercontent/pages/. If the pages are heavy in HTML,the source file should simply be an HTML document instead of reST/Markdown.By default, pages should use thereadthedocs_theme/templates/page.htmltemplate but that can be overridden.

Blog posts should be saved undercontent/posts/.

Our style is loosely based on theWikipedia Manual of Style.

• Titles usetitle case.
• Section headings (h2 and below) use sentence case and tend to bedescriptive/substantive beyond a simple noun.