Write the Docs website
This is the code that powers www.writethedocs.org. It contains information about the Write the Docs group, as well as information about writing documentation.
To contribute to the Write the Docs website, it's helpful to familiarize yourself with the Sphinx site generator, as well as reStructuredText markup syntax.
All of the generated website lives inside the
docs directory, but many files outside the
conf/ directory are just static RST, as in any other Sphinx project.
All RST files are rendered with Jinja, which allows the use of Jinja tags in all of them. A few custom Jinja filters are available for things like generating photo paths for speakers.
For conferences, see the conference site documentation.
An even more fragile process that needs documenting and fixing.
WIP (Work In Progress) Docs on how to do this:
_data/<year>.<city>.speakers.yaml, add a
youtubeId: 12345678901key value pair to each talk.
Make sure the directory
videos/<city>/<year>is included in the Video Archive
In the virtual environment, switch to the
docsdirectory and run
BUILD_VIDEOS=True make html.
Commit the relevant changed files:
If you want to preview locally:
BUILD_VIDEOS=True make livehtmland browse the new video pages at
If you run into trouble with broken links to video files, have a look at
Add a line at the end with the relevant places and dates.
Change to the
_extdirectory and run it:
Commit the fixed
Prerequisites for generating the docs locally
python 3.8.xusing your package manager, if not installed already. You'll probably need
rootprivileges to do this.
Generate a virtual environment for the WTD repo in the
virtualenv --python=/usr/bin/python3.8 venv
Installing the project requirements
Activate the virtual environment according to your operating system:
- On Linux-based systems, run
- On Windows using the Command Prompt, run
- On Windows using PowerShell, run
- On Windows using Git Bash, run
You'll need to do this every time you come back to the project.
- On Linux-based systems, run
In the repository root directory (
wwwby default), run
pip install -r requirements.txtto install sphinx and other requirements.
Previewing the docs locally
Remember to activate the virtual environment using the appropriate command for your OS and Shell before running the following commands.
- In the
make livehtmlto view the docs on http://127.0.0.1:8888/.
If you're not seeing new content in the local preview, run
make clean to delete the generated files, then
make livehtml to regenerate them.
The Write the Docs website is hosted on Read the Docs.
Updating the CSS
Styling is maintained in
docs/_static/conf/css/ as SASS. Convert SASS to minified CSS by installing SASS
npm install -g sass
and then running (using a 2022 example):
sass --style=compressed docs/_static/conf/scss/main-2022.scss docs/_static/conf/css/main-2022.min.css
After your work is complete, you can save resources by deactivating the virtual Python environment with the following command on Linux:
If you have verified this command on MacOS or Windows, we invite you to submit a PR to include that information here.