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.
Code Architecture
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.
Conference pages
For conferences, see the conference site documentation.
Videos
An even more fragile process which needs documenting and fixing.
WIP Docs on how to do this:
-
In
_data/<year>.<city>.speakers.yaml, add ayoutubeId: 12345678901key value pair to each talk. -
Make sure the directory
videos/<city>/<year>is included in the Video Archivetoctreeindocs/videos/index.rst. -
In the venv switch to the
docsdirectory and runBUILD_VIDEOS=True make html. -
Commit the the relevant changed files:
docs/videos/index.rst_data/<year>.<city>.speakers.yamldocs/videos/<city>/<year>/*
-
If you want to preview locally:
- Run
BUILD_VIDEOS=True make livehtmland browse the new video pages athttp://127.0.0.1:8888.
- Run
Troubleshooting
If you run into trouble with broken links to video files, have a look at _ext/fix_video_yaml.py:
-
Add a line at the end with the relevant places and dates
-
Change to the
_extdirectory and run it:python fix_video_yaml.py -
Commit the fixed
_data/<year>.<city>.speakers.yamlfile.
Prerequisites for generating the docs locally
-
Install
python 3.5.xusing your package manager, if not installed already.
You'll probably needrootprivileges to do this. -
Generate a virtual environment for the WTD repo in the
venvdirectory:virtualenv --python=/usr/bin/python3.5 venv
Installing the project requirements
-
Activate the virtual environment according to your operating system:
- On Linux-based systems, run
source venv/bin/activate. - On Windows using the Command Prompt, run
venv\Scripts\activate.bat. - On Windows using PowerShell, run
. venv\Scripts\activate.ps1. - On Windows using Git Bash, run
source venv\Scripts\activate.
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), runpip 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
docsdirectory, runmake 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.
Previewing changes on Netlify
You can preview changes you've made on a pull request by clicking "Show all checks" at the bottom of the pull request page, and then clicking "Details" on the Netflify line, and navigating to the page you're making changes to.
Updating the theme or css
If you need to update the theme, the original source is in
https://github.com/writethedocs/website-theme/
and instructions on how to update it are in the README.md
Updating CSS for the 2018 Theme
The website for 2018 uses SASS to compile all the assets it has. To modify the theme, you must first install the dependencies of
gulp. In the main directory, run:
npm install
With that you will install all the requirements to minify your CSS;
after that you only need to run:
# Generate everything and serve site
gulp
# Only generate assets
gulp styles
This has to be used alongside the sphinx server and it will
automatically minify all the content in your .scss files to the
main.min.css file. Also, gulp will be running browserify, allowing you
to see the CSS changes immediately in the browser.
