NC State University

How to Update This WebsiteΒΆ

This website is built with Sphinx, a Python based document generation tool. To update this website you’ll need the Sphinx tools installed, a clone of the Git repository of the website, and access to the AFS location where the production copy of the website lives.

First, let’s clone the Git repository:

$ git clone git://

Now you should have a linux-web/ directory with the source of this website. Inside that directory, let’s build a Python Virtual Environment that will contain all the Python tools needed. To do that, you will need the python-virtualenv RPM package installed. This is available in Fedora. For RHEL it can be found in the EPEL repository. This is the only action that requires root privileges.

# yum -y install python-virtualenv

Create the Python Virtual Environment:

$ pwd
$ virtualenv sphinx
New python executable in sphinx/bin/python
Installing setuptools............done.
Installing pip...............done.

Next, activate the Python environment. You’ll need to make sure to activate this virtual environment every time you wish to do work with Sphinx and this website.

$ source sphinx/bin/activate
(sphinx) $ pip install sphinx
Downloading/unpacking sphinx
Successfully installed sphinx Pygments Jinja2 docutils
Cleaning up...

The Git repository has several branches for several similar web sites for Campus Linux Services. You need to switch to the right branch for this website. The following table maps the branch name to the website it manages.

Branch Name Web Site

Check out the correct branch. In this example we will use secure as our branch and website to edit.

(sphinx) $ git checkout secure

At this point your environment is setup. In the future all you will need to do to work with this Sphinx website is change to this directory, activate the Python virtual environment, and start editing.

At this point you may edit the reStructuredText source files as needed. Templating and layout are controlled like they are for any Sphinx documentation project. Please refer to that documentation for questions about creating and updating the source.

Once you have completed a round of editing don’t forget to commit your changes to your local Git repository. You can build the HTML and test it by pointing your browser to what appears in _build/html/index.html by running the following command in the root of the documentation tree:

(sphinx) $ make html

When you are satisfied with your changes you should git push them to the upstream repository or ask to have that done for you. The writable location of the upstream repository accessed by the above git clone command is here:


Finally, change directory to where the production web site lives, git pull, and rebuild the production website. Once you are done, you can deactivate your Python Virtual Environment.

(sphinx) $ cd /afs/unity/web/l/linux/<branch-name>
(sphinx) $ git pull
(sphinx) $ make html
(sphinx) $ deactivate

Your website changes should now be online.

Previous topic


This Page