Arkindex user documentation

Plan

We plan to have three distinct sections:

• A tutorial that introduces new users or potential clients to the concepts and basic operations of Arkindex
  • Ideally, a single page
• More in-depth topics, e.g.:
  • Image management
  • IIIF compatibility
  • What happens after a git push for workers
  • Troubleshooting a process
• How-tos for specific processes
  • How to import a PDF
  • How to deploy Arkindex
  • How to run a Machine Learning process on elements
  • How to organize content

Setup

This section guides you through an initial set-up to write some docs.

Installing pre-commit

This repository uses pre-commit for basic sanity checks such as common spelling mistakes, line endings, unmerged conflicts, etc.

To install pre-commit

1. Run pip3 install pre-commit.
2. Run pre-commit install.

Installing Zola

Zola is the static site generator we use to build the docs as a website. You can install it and use it locally to see how your docs will look like.

You can follow the official setup instructions to get Zola on your machine.

⚠️ Make sure you have at least zola 0.13.0 to get syntax highlighting to work.

Clone submodules

This repository uses a submodule to point to the Zola theme we are using.

When the submodules are not loaded, running zola serve will result in an error similar to Error: No 'theme.toml' file found.

To clone submodules

1. Run git submodule update --init.

Writing docs

Style guide

To ensure we keep a consistent writing style, a style guide is available as STYLE.md.

Previewing your changes

With Zola installed, you can display the resulting website locally and see your changes be updated in real-time. A copy of the generated docs is also available online once you make your changes into a merge request on GitLab.

To preview your changes locally

1. Run zola serve at the root of this repository.
2. Open http://127.0.0.1:1111 in your web browser.

To preview your changes in a merge request

1. Push to GitLab and create a merge request.
2. Wait for the CI pipeline to be successful.
3. Click on the View app button to browse the generated docs.