From b4068cfb8d7b1534934e487bb3a954e40d5395ef Mon Sep 17 00:00:00 2001 From: eviau-artefactual Date: Thu, 27 Jun 2024 15:04:38 -0400 Subject: [PATCH 1/4] instructions: build offline, local docs --- README.md | 28 ++++++++++++++++++++++++++++ 1 file changed, 28 insertions(+) diff --git a/README.md b/README.md index 8ea05471..b2e955b8 100644 --- a/README.md +++ b/README.md @@ -12,6 +12,34 @@ You are free to copy, modify, and distribute the Archivematica 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: +`git clone https://github.com/artefactual/archivematica-docs.git` +- Move to the documentation repository with: +`cd archivematica-docs` +- Create a Python virtual environment to contain all the tools required to build the documentation: +`python3 -m venv .env` +- Activate the virtual environment: +`source .env/bin/activate` +- Install the requirements: +`pip install -r requirements.txt` +- Build the documentation: +`sphinx-build -D language=en ./ _build/html/en` for English +`sphinx-build -D language=es ./ _build/html/es` for *español* (Spanish) +`sphinx-build -D language=fr ./ _build/html/fr` for *français* (French) +`sphinx-build -D language=pt_BR ./ _build/html/pt_BR` for *português do Brasil* (Brazilian Portuguese) +- Access the documentation: +`open _build/html/index.html` + +The HTML files for the documentation will be in `archivematica-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. + ## Contributing Thank you for considering a contribution to the Archivematica documentation! For From 15ef6203d9c4f91259095c2b15dd2a30bd687c0f Mon Sep 17 00:00:00 2001 From: eviau-artefactual Date: Thu, 27 Jun 2024 15:13:36 -0400 Subject: [PATCH 2/4] formatting --- README.md | 42 ++++++++++++++++++++++++++++++++---------- 1 file changed, 32 insertions(+), 10 deletions(-) diff --git a/README.md b/README.md index b2e955b8..8192915e 100644 --- a/README.md +++ b/README.md @@ -19,22 +19,44 @@ 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: -`git clone https://github.com/artefactual/archivematica-docs.git` +``` +git clone https://github.com/artefactual/archivematica-docs.git +``` + - Move to the documentation repository with: -`cd archivematica-docs` +``` +cd archivematica-docs +``` + - Create a Python virtual environment to contain all the tools required to build the documentation: -`python3 -m venv .env` +``` +python3 -m venv .env +``` + - Activate the virtual environment: -`source .env/bin/activate` +``` +source .env/bin/activate +``` + - Install the requirements: -`pip install -r requirements.txt` +``` +pip install -r requirements.txt +``` + - Build the documentation: -`sphinx-build -D language=en ./ _build/html/en` for English -`sphinx-build -D language=es ./ _build/html/es` for *español* (Spanish) -`sphinx-build -D language=fr ./ _build/html/fr` for *français* (French) -`sphinx-build -D language=pt_BR ./ _build/html/pt_BR` for *português do Brasil* (Brazilian Portuguese) +``` +sphinx-build -D language=en ./ _build/html/en # for English + +sphinx-build -D language=es ./ _build/html/es # for *español* (Spanish) + +sphinx-build -D language=fr ./ _build/html/fr # for *français* (French) + +sphinx-build -D language=pt_BR ./ _build/html/pt_BR # for *português do Brasil* (Brazilian Portuguese) +``` - Access the documentation: -`open _build/html/index.html` +``` +open _build/html/index.html +``` The HTML files for the documentation will be in `archivematica-docs/_build/html/`. You can open the files in a browser of your choice, without having any access to the Internet. From 4b0cbfb89346b49ab73a69fedba068d238a99be9 Mon Sep 17 00:00:00 2001 From: eviau-artefactual Date: Thu, 27 Jun 2024 15:21:47 -0400 Subject: [PATCH 3/4] fix markdownlint --- README.md | 50 +++++++++++++++++++++++++++++++------------------- 1 file changed, 31 insertions(+), 19 deletions(-) diff --git a/README.md b/README.md index 8192915e..cb2f24e7 100644 --- a/README.md +++ b/README.md @@ -16,51 +16,63 @@ with attribution under the terms of the Creative Commons Attribution Share Alike 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: -``` +* 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-docs.git ``` -- Move to the documentation repository with: -``` +* Move to the documentation repository with: + +```bash cd archivematica-docs ``` -- Create a Python virtual environment to contain all the tools required to build the documentation: -``` +* Create a Python virtual environment to contain all the required tools: + +```bash python3 -m venv .env ``` -- Activate the virtual environment: -``` +* Activate the virtual environment: + +```bash source .env/bin/activate ``` -- Install the requirements: -``` +* Install the requirements: + +```bash pip install -r requirements.txt ``` -- Build the documentation: -``` +* Build the documentation: + +```bash sphinx-build -D language=en ./ _build/html/en # for English sphinx-build -D language=es ./ _build/html/es # for *español* (Spanish) -sphinx-build -D language=fr ./ _build/html/fr # for *français* (French) +sphinx-build -D language=fr ./ _build/html/fr # for *français* (French) sphinx-build -D language=pt_BR ./ _build/html/pt_BR # for *português do Brasil* (Brazilian Portuguese) ``` -- Access the documentation: -``` + +* Access the documentation: + +```bash open _build/html/index.html ``` -The HTML files for the documentation will be in `archivematica-docs/_build/html/`. You can open the files in a browser of your choice, without having any access to the Internet. +The HTML files for the documentation will be in +`archivematica-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. +While this offline version will not have the Archivematica web theme, you will +gain access to improved search features. ## Contributing From a373c97d635491d9b90c33147e96d1646cf8ad49 Mon Sep 17 00:00:00 2001 From: eviau-artefactual Date: Mon, 8 Jul 2024 15:44:08 -0400 Subject: [PATCH 4/4] Update to mention the lack of Storage Service docs --- README.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/README.md b/README.md index cb2f24e7..12c53fac 100644 --- a/README.md +++ b/README.md @@ -74,6 +74,11 @@ 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 documentation; notably +the Archivematica Storage Service docs will be missing. Instructions on how to +build a local, offline version of the Archivematica Storage Service is +available on its [GitHub repo](https://github.com/artefactual/archivematica-storage-service-docs). + ## Contributing Thank you for considering a contribution to the Archivematica documentation! For