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.
The repo is still in its early stages; feel free to contribute information that you might want to share with the community. 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.
You'll probably need root
privileges to install the prerequisites.
-
Install
python 2.7.x
using your package manager. -
If your version of Python as shown by
python -V
is <=2.7.9
:- download and install pip.
- install
virtualenv
using your package manager.
-
If you have already been using
virtualenv
with a different version of Python, you may need to runvirtualenv --python=/usr/bin/python2.7 <path/to/new/virtualenv>
to havevirtualenv
use the 2.7 interpreter.
-
In the repository root directory (
www
by default), create a virtual environment for the project requirements by runningvirtualenv venv
. More info onvirtualenv
can be found here. -
On Linux-based systems, activate the virtual environment by running
source venv/bin/activate
. On Windows using the Command Prompt, runvenv\Scripts\activate.bat
. On Windows using PowerShell, run. venv\Scripts\activate.ps1
. On Windows using Git Bash, runsource venv\Scripts\activate
. You'll need to do this every time you come back to the project. -
In the repository root directory (
www
by default), runpip install -r requirements.txt
to install sphinx and other requirements.
Remember to activate the virtual environment using the appropriate command for your OS and Shell before running the following commands.
- In the
docs
directory, runmake livehtml
to 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.
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:
http://writethedocs-staging.readthedocs.io/en/staging/
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
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:
gulp
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.
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-portland-2018.yaml
todocs/_data/config-prague-2018.yaml
. Edit the file as necessary. - The conference directory. For example
docs/conf/portland/2018
todocs/conf/prague/2018
. - The templates. For example
docs/_templates/2018/base_na.html
anddocs/_templates/2018/na
todocs/_templates/2018/base_eu.html
anddocs/_templates/2018/eu
. - You might need some local content in
docs/includes/conf
and_static
. Sphinx will probably warn you if you do.
Search and replace any year specific stuff (CAREFUL)
portland/2018
Manually update any FIXME comments
.. FIXME
For this whole thing to work we still need to implement these
.. TODO