writethedocs/www: Local Development for the Write the Docs Website

What writethedocs/www contains and who uses it

writethedocs/www is the source repository for the main Write the Docs website at `http://www.writethedocs.org`. Its purpose is site maintenance rather than a reusable documentation framework. The README says the repository contains information about the Write the Docs group and information about writing documentation. Conference content has a separate set of instructions on the conference site documentation page.

The likely users are contributors who want to correct or extend website copy, prepare conference pages, maintain templates, or adjust the site's presentation. The repository also supports maintainers working through the site's build configuration and generated search index. It does not appear to be an application that receives user requests or stores operational data. Its output is a static website generated from source files.

That distinction matters when evaluating the project. A contributor looking for a hosted Write the Docs documentation workspace will not find that product here. A documentation author looking for a turnkey theme can inspect the configuration and templates, but adopting this repository means accepting the structure and content rules of the Write the Docs site. The README specifically points contributors to Sphinx and reStructuredText, so those tools form part of the required working knowledge.

Sphinx source, Jinja processing, and static assets

The site's generated files live inside `docs`. Many files outside `docs/conf/` are ordinary static reStructuredText pages, while the `conf/` directory contains the Sphinx site configuration and supporting structure. The README states that all RST files are rendered with Jinja, which makes Jinja tags available inside the reStructuredText source. Custom filters include functionality for generating paths for speaker photos.

The Python project declares Sphinx 8.1 or later within the supported range, along with `myst-parser`, `ablog`, `sphinxcontrib-datatemplates`, `sphinx-notfound-page`, `sphinxext-opengraph`, and other packages. `pystemmer` is included for the search index. The optional `scripts` dependency group is separate from the normal site build and contains tools used by helper scripts in `docs/_scripts/`. This separation reduces the amount installed for a basic build, but it also means contributors who edit those helpers need an additional synchronization step.

The repository also contains `docs/_static/conf/scss/`, where styling is maintained as SASS. Generated minified CSS files live under `docs/_static/conf/css/`. The top-level `pyproject.toml`, `uv.lock`, `.readthedocs.yaml`, and `dockerfile` indicate that local and hosted builds are configured through project files rather than an ad hoc script. The README does not document a content-management interface, so editing is file based.

Setting up uv for a local site preview

The documented local setup starts with `uv`. From the repository root, `uv sync` installs Python 3.12 and the dependencies needed to generate the documentation. The README says the root directory is `www` by default. If you intend to change the helper scripts in `docs/_scripts/`, use the dependency group command instead of assuming that the normal installation includes those packages.

After installation, activate the virtual environment with the command appropriate for your operating system and shell. The README does not give one universal activation command, so that choice belongs to your local environment. Then run the live preview from the `docs` directory. The site is documented at `http://127.0.0.1:8888/`.

If an edit does not appear in the preview, the README gives a cleanup and regeneration path. The `make clean` command removes generated files before `uv run make livehtml` rebuilds them. This is a documented recovery step for stale generated output, not a general troubleshooting guarantee.

Building the first local preview

The shortest documented local path is to install `uv`, synchronize the repository, change into `docs`, and start the live build. The first command below is the dependency installation step. It also establishes the Python 3.12 requirement declared by `pyproject.toml`.

uv sync

If you need the packages used by `docs/_scripts/`, run this from the repository root. The scripts group is optional according to the project configuration.

uv sync --group scripts

After activating the environment, run the following command from `docs`. The README identifies the expected local address as `http://127.0.0.1:8888/`.

uv run make livehtml

A clean regeneration is available when generated content appears stale.

make clean
uv run make livehtml

The README does not document automated browser tests, a separate API, or a production deployment command. A successful local preview confirms that the source can be rendered, but it does not by itself verify every conference page or production environment setting.

Docker and devcontainer alternatives to host Python

For contributors who do not want to configure Python directly on the host, the repository supplies a `dockerfile` and a `.devcontainer/` directory. The README describes the Docker image as a barebones environment for running the site through Docker Desktop. The image is built from the repository root, then exposed on port 8888.

docker build -t wtd .

After the image exists, the documented run command publishes the container's site on the host's port 8888.

docker run -p 8888:8888 wtd

The browser should then open `http://localhost:8888`. The README notes that the container and image remain visible in Docker Desktop. This approach is useful when host Python and dependency configuration would interfere with the contributor's normal work. It also introduces Docker Desktop as an additional dependency and keeps the preview inside a separate environment.

The devcontainer is the other documented option. The README directs contributors to open the project in a supported IDE and select "Open in devcontainer". It states that the development environment then starts in a containerized environment. It does not provide a command-line initialization sequence, so editors and IDE support are part of the documented workflow rather than optional details.

Updating SASS without confusing source and generated CSS

Styling is not edited directly in the minified CSS output. The README locates maintained SASS files in `docs/_static/conf/scss/` and identifies `docs/_static/conf/css/` as the destination for generated CSS. It gives a 2022 example rather than a generic current-year command, which is worth preserving when checking the exact source and output files.

The documented prerequisite is a global SASS installation:

npm install -g sass

The conversion command below compresses the named SASS file into the named CSS file. It is an explicit file-to-file operation, not a repository-wide stylesheet command.

sass --style=compressed docs/_static/conf/scss/main-2022.scss docs/_static/conf/css/main-2022.min.css

This workflow creates a maintenance boundary between authored styles and generated output. A contributor changing the example file would need to adapt the paths, but the README does not define a general naming convention or a command for processing every stylesheet. The repository also contains no GitHub releases, so there is no release artifact from which to infer a packaged stylesheet workflow.

Limits of the repository and the alternative to a hosted build

The clearest limitation is scope. This repository builds the Write the Docs website, but it is not documented as a reusable service for hosting arbitrary documentation projects. Its pages, conference structure, templates, speaker filters, and content conventions belong to that site. Reusing the repository as a generic documentation foundation would require checking configuration, content ownership, and branding rather than copying only the Python dependencies.

A practical alternative is Read the Docs hosting. The README states that the Write the Docs website is hosted on Read the Docs. That service handles the hosted build path, while this repository remains the source that contributors edit. The distinction is useful: use Read the Docs when the goal is the published site and its managed build, and use the local Sphinx workflow when reviewing changes before submission.

Another alternative is a conventional local Python environment, because the README requires familiarity with `venv` and says to activate a virtual environment before previewing. Docker and devcontainers reduce host setup differences, but they do not remove the need to understand Sphinx and reStructuredText. The choice is operational rather than a claim that one rendering approach is better.

The last push was on 2026-10-15, and the repository is not archived. The README does not describe a release cadence, upgrade policy, or rollback procedure. Since no GitHub releases are listed, contributors should not assume that a tagged version provides a stable upgrade target.

Editorial conclusion

Adopt this repository if you need to contribute to www.writethedocs.org and are comfortable with Sphinx, reStructuredText, templates, or a Docker container. Do not treat it as a general documentation platform or a deployable standalone application without checking its Sphinx configuration. Before contributing, verify that `uv sync` installs the intended Python 3.12 environment, inspect `LICENSE.md` for the custom terms, and confirm whether your changes require the optional `scripts` dependency group or a local SASS tool.

Frequently asked questions

Official sources

1. Issues
2. Project website
3. README
4. writethedocs/www on GitHub