Technical details

The Archivematica project uses the Sphinx Documentation Generator as the basis for the Archivematica manuals. Sphinx is an open-source documentation generator that uses reStructuredText (reST) markup format as its basis, and converts reST files into HTML, PDF, and EPub formats. It enforces indexes and versioning, two things that help keep the documentation streamlined and well-organized.

reStructuredText (reST) is a lightweight markup language used in Sphinx documentation, which is human-readable in either raw (e.g. the text file itself) or processed (e.g. HTML document) form.

Editing on GitHub

You can edit the documentation directly on GitHub and send in a pull request through the user interface. This is ideal for smaller changes. If you have larger changes to suggest, we recommend that you edit the files locally so that you can check the formatting using Sphinx's HTML document generator.

For more information on using the GitHub UI to propose changes, see the Contributing guide for community members.

Editing locally

It's also possible to edit the documentation locally using a text editor on your computer. This is recommended if you have a large change to suggest or you want to include new screenshots, so that you can use Sphinx's HTML document generator to inspect the results and look for errors.

You must first install Sphinx and clone the documentation repository:

1. Install pip: sudo apt-get install python-pip
2. Install Sphinx: sudo pip install -U Sphinx
3. Locate the clone link by going to the main page of the repository, clicking on Clone or download, and copying the URL. In this case, the URL is [email protected]:artefactual/archivematica-docs.git
4. Clone the documentation repository: git clone [email protected]:artefactual/archivematica-docs.git
5. Run git pull --rebase to make sure you’re up to date.

For more information on using the GitHub UI to propose changes, see the Sphinx section of the Contributing guide for community members.

Artefactual staff should edit documentation locally and push changes through github. See the Contributing guide for Artefactual staff for more information.