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.
Prerequisites for generating the docs locally
You'll probably need
root privileges to install the prerequisites.
python 3.6.xusing your package manager.
Generate a virtual environment for the WTD repo in the
virtualenv --python=/usr/bin/python3.6 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.
Viewing changes on staging
If you you can't run
make livehtml locally, or don't want to, you can preview
changes by merging them into the
staging branch and pushing that to GitHub.
If your feature branch is
changes-to-test you would do something like:
git checkout staging git pull git merge changes-to-test git push
Unless there are merge conflicts you need to resolve, when you push those changes a build is triggered on Read the Docs and when it is finished you can preview your changes on:
Updating the theme or css
If you need to update the theme, the original source is in
and instructions on how to update it are in the
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:
With that you will install all the requirements to minify your CSS; after that you only need to run:
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.
Generating new conf pages
Copy and Create
There are a few places you need to copy files from when spinning up a new conference site:
- The YAML config file. For example, copy
docs/_data/config-prague-2018.yaml. Edit the file as necessary.
- The conference directory. For example
- The templates. For example
- You might need some local content in
_static. Sphinx will probably warn you if you do.
Search and replace
Search and replace any year specific stuff (CAREFUL)
Manually update any FIXME comments
For this whole thing to work we still need to implement these