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.

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 check the formatting using 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.