Creating a documentation project


Virtualenv is a tool to set-up an isolated environment you can use to test a Python version or packages. After activating the environment, packages can be installed directly with pip. It seperates the version of Python you use here from the systemwide Python version. Very handy if you don't want to mess up your system.

After setting up a virtualenv folder, we'll install Sphinx. Sphinx allows you to convert files in rst format to html files. Sphinx is alos able to produce documentation on your code. There are different themes or you can roll your own.

1. Installing the environment

We'll install a normal virtual env project and use that to edit our rst docs.

1.1 Install a virtualenv

We make a project out of our documentation so we start off by creating a virtual environment. Create a folder in your home directory, and create the virtualenv directory:

mkdir development_docs
cd development_docs
virtualenv venv

On Debian, the python version of stable 3.4.2. produces an error when trying to create such a virtualenv folder. You could use another version of Python, build your own version or create the virtualenv without pip and then afterwards install pip in the virtualenv. To use this last method, and only use the following if you get the error metioned otherwise, skip to section '1.2 upgrade pip':

mkdir development_docs
cd development_docs
virtualenv --no-pip venv
source venv/bin/activate

Now we're in the environment, we get the '' file and use this to install pip in our environment.:

curl -O

When creating a virtualenv, virtualenv might not be on your system. You can install virtualenv with apt:

apt-get install python3-virtualenv

You can create a virtualenv with newer versions of Python:

python -m "venv" venv

1.2 Upgrade pip

pip is installed but we want the latest version:

pip install --upgrade pip

1.3 Install Sphinx

Sphinx is a tool to convert reST documentation to html or pdf. We'll install it in this project:

pip install Sphinx

1.4 Make the doc directory

We make a directory that will hold our documentation files or rst files and then built html files:

mkdir doc

Run sphinx-quickstart and answer the questions. You'll want the autodoc module if you wish to document code in this virtualenv. We'll call the project "Development Information":


1.5 Prepare for Git

Next, we will put the doc directory under source revision. This allows us to track changes to docs and revert in case of misfortune :) Our prefereed tool for this is Git. I will post on Git in another blog post.

If git is not installed yet:

apt-get install git

After installation git, we can create a repository. Initialize git, enter your contact details and come up with a better description than I did fa-lightbulb orange bigicon fa fa-smile green bigicon

git init
git config --global "Your name"
git config --global "youremail"
echo "Documentation of how we setup and run our development environment" > .git/description

We want to ignore certain files. Create a .gitignore file:

vi .gitignore
# Lines starting with '#' are comments.

We will check what files/dirs are new:

git status

Next we will add what we want to track. In this case our .gitignore file and the doc subdirectory:

git add .gitignore
git add doc

Next commit the changes:

git commit -am "Initial commit of our development documentation"

1.6 Make a repository on the server

If you want to push the repository to a server, follow the next steps, if not, just skip these steps. Log on the the remote server, and make a directory for the project. Initialize the repository on the server:

cd /home/user/repositories/projects
mkdir development_docs
cd development_docs
git --bare init

Note that you won't see your files in a bare repository as you would in the local repository.

2. Upload the code to the code server

2.1 Send code to the server


This part is done from your local machine again

Our workflow for a branch is this:

  • Create a remote branch
  • Create a local branch that tracks it
  • Work, Test, Commit (repeat) – this is all local
  • Push (pushes commits to the remote repository)

To see what remote servers we have configured:

git remote

First we specify the default remote location. Just as if the code was cloned from another git repository, we'll call it origin:

git remote add origin ssh://user@server/~/repositories/projects/development_docs

We'll try to push our documentation to the repository on the server:

git push origin master

Next time, we can just use:

git push

We can also set our current branch to track the master branch on the server. This is what we want:

git branch --set-upstream master origin/master

Another way to achieve the above, is to just edit the .git/config file. Add a section:

[remote "origin"]
fetch = +refs/heads/*:refs/remotes/origin/*
url = ssh://user@server/~/repositories/projects/development_docs

At the end of the file, add this:

[branch "master"]
remote = origin
merge = refs/heads/master

2.2 Check

We'll need to check everything is setup ok:

git config --get remote.origin.url

2.3 Test export from the server

Try to clone the remote repository:

cd /tmp
mkdir test
cd test
git clone git+ssh://user@server/~/repositories/projects/development_docs

Now you're all set to create documentation on your own.