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.

To make changes in the Github user interface:

1. Find the .rst file that you want to edit. If you wanted to edit the Administrator FAQ, for example, you would navigate to archivematica-docs/admin-manual/maintenance/maintenance.rst, which contains the FAQ.
2. Click on the pencil icon to edit the file. When the editor opens, a blue box at the top of the page will read:

You’re editing a file in a project you don’t have write access to. We’ve created a fork of this project for you to commit your proposed changes to. Submitting a change to this file will write it to a new branch in your fork, so you can send a pull request.

3. Make your desired changes. Please remember to consult the style guide before you write.
4. Include a commit message explaining the rationale behind your changes.
5. Click on Propose file change
6. You'll be taken to a page where you can compare changes and start a pull request. At the top of the page, ensure that the following information is correct:
   • Base fork: artefactual/archivematica-docs
   • Base: Branch of the documentation that you want to edit (e.g. 1.7).
   • Head fork: your-username/archivematica-docs
   • Compare: The branch place you made your edits. Often this is given a default name like patch-1.
7. Click on Create pull request to submit your changes.

Once you've created a pull request, Artefactual staff will review it and provide feedback, if needed.

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.