Documentation

Quick Fix

If you find a typo or a small error in the documentation you can easily fix it using GitHub.

  • Fork the repository

  • Go to [your GitHub username]/dataverse/doc/sphinx-guides/source and access the file you would like to fix

  • Switch to the branch that is currently under development

  • Click the Edit button in the upper-right corner and fix the error

  • Submit a pull request

Other Changes (Sphinx)

The documentation for Dataverse was written using Sphinx (http://sphinx-doc.org/). If you are interested in suggesting changes or updates we recommend that you create the html files using Sphinx locally and the submit a pull request through GitHub. Here are the instructions on how to proceed:

Installing Sphinx

On a Mac:

Download the sphinx zip file from http://sphinx-doc.org/install.html

Unzip it somewhere. In the unzipped directory, do the following as root, (sudo -i):

python setup.py build python setup.py install

Alternative option (Mac/Unix/Windows):

Unless you already have it, install pip (https://pip.pypa.io/en/latest/installing.html)

run pip install sphinx in a terminal

This is all you need. You should now be able to build HTML/pdf documentation from git sources locally.

Using Sphinx

First, you will need to make a fork of the dataverse repository in GitHub. Then, you will need to make a clone of your fork so you can manipulate the files outside GitHub.

To edit the existing documentation go to ~/dataverse/doc/sphinx-guides/source directory inside your clone. There, you will find the .rst files that correspond to the guides in the dataverse page (http://guides.dataverse.org/en/latest/user/index.html). Now, using your preferred text editor, open and edit these files, or create new .rst files and edit the others accordingly.

Once you are done, open a terminal and change directories to ~/dataverse/doc/sphinx-guides . Then, run the following commands:

  • make clean

  • make html

After sphinx is done processing the files you should notice that the html folder in ~/dataverse/doc/sphinx-guides/build directory has been updated. You can click on the files in the html folder to preview the changes.

Now you can make a commit with the changes to your own fork in GitHub and submit a pull request to the dataverse repository.

Table of Contents

Every non-index page should use the following code to display a table of contents of internal sub-headings:

.. contents:: |toctitle|
        :local:

This code should be placed right after any introductory text/images and directly before the first subheading, much like a Wikipedia page.

Images

A good documentation is just like a website enhanced and upgraded by adding high quality and self-explanatory images. Often images depict a lot of written text in a simple manner. Within our Sphinx docs, you can add them in two ways: a) add a PNG image directly and include or b) use inline description languages like GraphViz (current only option).

While PNGs in the git repo can be linked directly via URL, Sphinx-generated images do not need a manual step and might provide higher visual quality. Especially in terms of quality of content, generated images can be extendend and improved by a textbased and reviewable commit, without needing raw data or source files and no diff around.

GraphViz based images

In some parts of the documentation, graphs are rendered as images via Sphinx GraphViz extension.

This requires GraphViz installed and either dot on the path or adding options to the make call.

This has been tested and works on Mac, Linux, and Windows. If you have not properly configured GraphViz, then the worst thing that might happen is a warning and missing images in your local documentation build.

Versions

For installations hosting their own copies of the guides, note that as each version of Dataverse is released, there is an updated version of the guides released with it. Google and other search engines index all versions, which may confuse users who discover your guides in the search results as to which version they should be looking at. When learning about your installation from the search results, it is best to be viewing the latest version.

In order to make it clear to the crawlers that we only want the latest version discoverable in their search results, we suggest adding this to your robots.txt file:

User-agent: *
Allow: /en/latest/
Disallow: /en/

Previous: Testing | Next: Dependency Management