diff --git a/.gitignore b/.gitignore index cbe989b..bd3a388 100644 --- a/.gitignore +++ b/.gitignore @@ -1,3 +1,4 @@ /_build *.DS_Store *~ +.env/ diff --git a/README.md b/README.md index 451f985..90a71be 100644 --- a/README.md +++ b/README.md @@ -13,6 +13,67 @@ documentation with attribution under the terms of the Creative Commons Attribution Share Alike 4.0 (CC-BY-SA-4.0) license. See the [LICENCE](LICENCE) file for details. +## Building the documentation locally + +To build a local, offline version of the documentation: + +* Decide where the documentation will be stored on your computer. +* In a Terminal window, use the `cd` command to navigate to this location. +* Create a local copy of the documentation by running: + +```bash +git clone https://github.com/artefactual/archivematica-storage-service-docs.git +``` + +* Move to the documentation repository with: + +```bash +cd archivematica-storage-service-docs +``` + +* Create a Python virtual environment to contain all the required tools: + +```bash +python3 -m venv .env +``` + +* Activate the virtual environment: + +```bash +source .env/bin/activate +``` + +* Install the requirements: + +```bash +pip install -r requirements.txt +``` + +* Build the documentation: + +```bash +sphinx-build -D language=en ./ _build/html/en # for English +``` + +* Access the documentation: + +```bash +open _build/html/ +``` + +The HTML files for the documentation will be in +`archivematica-storage-service-docs/_build/html/`. +You can open the files in a browser of your choice, without having any access +to the Internet. + +While this offline version will not have the Archivematica web theme, you will +gain access to improved search features. + +This local version will contain only the Archivematica Storage Service +documentation; notably the Archivematica docs will be missing. Instructions on +how to build a local, offline version of the Archivematica docs is available on its +[GitHub repo](https://github.com/artefactual/archivematica-docs). + ## Contributing Thank you for considering a contribution to the Archivematica Storage Service