perfSONAR Documentation

This repository contains installation and configuration documentation related to the perfSONAR project. The master branch contains the raw files for the documents hosted at http://docs.perfsonar.net. See the remainder of the README for more information on editing and deploying the perfSONAR documentation.

Documentation Format

The perfSONAR documentation is generated by Sphinx and uses the reStructuredText format. See those sites for details.

Preparing Your Environment

You will need to build the files using the Sphinx Python Library. You can do this directly on your system or use the proviided docker container.

You can start the container as follows:

cp env.example .env 
docker-compose up -d

Fill-in any git credentials in .env if you plan to use deploy scripts. Any of the commands in the remainder of this document can be executed with docker-compose exec docs_build COMMAND and will run inside container.

Alternatively, for direct install on most systems this means running the following:

pip install sphinx

See http://sphinx-doc.org/install.html for operating system specific instructions.

Previewing the site

From the top-level directory of this repository run:

make html

This will generate a set of HTML files that can be opened in your browser under _build/html/. You can view the main page by opening _build/html/index.html in your browser.

Deploying Documentation to docs.perfsonar.net

Simply push your changes to the master branch and the documentation will be published within 15 minutes to http://docs.perfsonar.net. This is handled by a script running on the hosting server that polls the git repository every 15 minutes and rebuilds the site if changes are detected. If you can't wait that long, run make html followed by deploy.sh to deploy your changes.

Deploying a release candidate

A script is provided to deploy documentation for a release candidate. The basic process is that the documentation for the release candidate is done in a branch and then we push out the branch using a shell script.

Once your branch is ready simply run the deploy_release_candidate.sh script to publish the branch (substituting BRANCH with the BRANCH name):

./deploy_release_candidate.sh BRANCH

This will create a new directory with the docs at http://docs.perfsonar.net/release_candidates/BRANCH. If you need to update existing docs, simply run the script again to push out changes.

Deploying a previous release

A script is provided to deploy documentation for previous releases. The basic process is that the documentation for the previous release must be tagged on master where the version number is the tag. This will in turn create a link under /previous_releases/VERSION with the old version of the documentation.

Following the process above, the first step is to create the tag, where TAG is the version number (e.g. 3.4.2) and COMMIT is the commit hash (e.g. 4305a6e72c0df0b929412fea19f7402f74b1ab8f):

git tag TAG COMMIT

Next we simply run the deploy_prev_release.sh script to publish the tag (again substituting TAG with the version number):

./deploy_prev_release.sh TAG

Finally, you will want to add a link to previous_releases.rst and publish by hand when you are ready to share.