Skip to content

Overview of Archipelago Documentation

Jump to bottom
Albert Min edited this page Aug 26, 2022 · 1 revision

Source Repos for Documentation

Main Documentation repo:

Deployment repos that trigger Documentation Build:

Documentation Build

The final built site is deployed on the gh-pages branch. If the build process goes awry and clobbers the site, folder/file structure, etc., you can push to this branch with the correctly built site.

CI Customizations

During the CI's automated deployment some commands are run to copy over files from the deployment repos and make some file name and text edits. Among these are the following:

  • The main repo READMEs are normalized (lower case) and prepended with the repo names: 
    cp ./archipelago-deployment/README.md ./tmp-update-repo/docs/archipelago-deployment-readme.md
cp ./archipelago-deployment-live/README.md ./tmp-update-repo/docs/archipelago-deployment-live-readme.md
  • For each markdown file in the docs folder, the repo name is prepended to the file name before being copied to the main documenation repo. Additionally, any linked references in the same documents are updated (sed commands): 
    for f in ./archipelago-deployment/docs/*.md; do cp -- "$f" "./tmp-update-repo/docs/archipelago-deployment-$(basename $f)"; done
for f in ./archipelago-deployment/docs/*.md; do for g in ./archipelago-deployment/docs/*.md; do sed -i "s/$(basename $g)/archipelago-deployment-$(basename $g)/g" "./tmp-update-repo/docs/archipelago-deployment-$(basename $f)"; done; done
for f in ./archipelago-deployment-live/docs/*.md; do cp -- "$f" "./tmp-update-repo/docs/archipelago-deployment-live-$(basename $f)"; done
for f in ./archipelago-deployment-live/docs/*.md; do for g in ./archipelago-deployment-live/docs/*.md; do sed -i "s/$(basename $g)/archipelago-deployment-live-$(basename $g)/g" "./tmp-update-repo/docs/archipelago-deployment-live-$(basename $f)"; done; done
  • So the deployment repo docs can be encoded with frontmatter (titles, tags, and any other metadata) without having it appear in the docs when read directly on the repos themselves, some commented out sections are uncommented with sed commands as they are copied to the documentation repo: 
    sed -i '/<!--documentation/d;/documentation-->/d;s/docs\//archipelago-deployment-/g' docs/archipelago-deployment-*.md
    Here is an example of the commented out frontmatter before the sed command uncomments them: 
    <!--documentation
---
title: "Adding Demo Archipelago Digital Objects (ADOs) to your Repository"
tags:
  - Archipelago Digital Objects
  - Demo Content
---
documentation-->
  • In a similar fashion to above, there is some theme-specific syntax (like admonitions as in this example) that are switched out with sed commands: 
    sed -i '/<!--switch_below/d;/<!--switch_above/d;s/switch_above-->/repo_docs-->/g;s/switch_below-->/<!--repo_docs/g' docs/archipelago-deployment-*.md
    And below is an example of the commented out sections that are switched out with the sed command above: 
    <!--switch_below

??? info "OSX (macOS)/x86-64"

    ```shell
    cp docker-compose-osx.yml docker-compose.yml
    ```

??? info "Linux/x86-64/AMD64"

    ```shell
    cp docker-compose-linux.yml docker-compose.yml
    ```

??? info "OSX (macOS)/Linux/ARM64"

    ```shell
    cp docker-compose-arm64.yml docker-compose.yml
    ```

switch_below-->

___

OSX (macOS)/x86-64:

```shell
cp docker-compose-osx.yml docker-compose.yml
```

___

Linux/x86-64/AMD64:

```shell
cp docker-compose-linux.yml docker-compose.yml
```

___

OSX (macOS)/Linux/ARM64:

```shell
cp docker-compose-arm64.yml docker-compose.yml
```

___

<!--switch_above
switch_above-->
    Everything between the switch_below tags is uncommented to be processed by the theme, and everything between the switch_below tag closure and the switch_above tags is commented out, i.e. switched out with the following result: 
    ??? info "OSX (macOS)/x86-64"

    ```shell
    cp docker-compose-osx.yml docker-compose.yml
    ```

??? info "Linux/x86-64/AMD64"

    ```shell
    cp docker-compose-linux.yml docker-compose.yml
    ```

??? info "OSX (macOS)/Linux/ARM64"

    ```shell
    cp docker-compose-arm64.yml docker-compose.yml
    ```

<!--repo_docs

___

OSX (macOS)/x86-64:

```shell
cp docker-compose-osx.yml docker-compose.yml
```

___

Linux/x86-64/AMD64:

```shell
cp docker-compose-linux.yml docker-compose.yml
```

___

OSX (macOS)/Linux/ARM64:

```shell
cp docker-compose-arm64.yml docker-compose.yml
```

___

repo_docs-->

Release

  1. First create the new documentation release branch, e.g. 1.1.0, at the main documentation repo.
  2. Update all references from the old branch to the new branch, e.g. 1.0.0 to 1.1.0, in the CI YAML file (.github/workflows/ci.yml) for the main documentation repo.
  3. Push changes or merge pull request for the CI file and new release branch.
  4. Update references in the CI YAML file (.github/workflows/ci.yml) for repo branches that trigger the documentation repo CI and push changes/merge pull request.
  5. If all goes well, both the main READMEs and any documentation in the docs folder should automatically have copied over to the main documentation repo, and the log for the CI being triggered will be here.

Files

Root files

  • Version branches each have a file in the root folder to trigger the workflow: .github/workflows/ci.yml
  • The mkdocs configuration file, which determines the plugins, theme (mkdocs-material), table of contents, icons, layout, etc. is also at root: mkdocs.yml

docs folder

  • The CNAME file contains the site subdomain and should not be changed or moved.
  • The actual documentation pages are all markdown files in the docs folder.
  • Any images should be put in the images (subfolder to docs) folder and added to pages with relative path.

To Update/Add Documentation

  1. Fork/clone the docs branch (currently only 1.0.0): git clone https://github.com/esmero/archipelago-documentation.git
  2. Create or update an existing markdown file.
    • To add tags to the page, create frontmatter at the top of the page with a title and list of tags, e.g.: 
      ---
title: "Archipelago-deployment for Drupal 9"
tags:
- Archipelago-deployment
- Drupal 9
- Docker
---
    • For horizontal rule use ___ instead of --- (because the latter is interpreted as frontmatter).
  3. Deploy and run locally.
    1. Install mkdocs-material (includes mkdocs), mike, and mkdocs-plugin-tags: pip install mkdocs-material mike git+https://github.com/jldiaz/mkdocs-plugin-tags.git
    2. From root of project: mike deploy --update-aliases BRANCH/VERSION-ALIAS (use --push flag to push changes to repo)
    3. If setting default version: mike set-default BRANCH/VERSION-ALIAS (use --push flag to push changes to repo)
    4. mike serve
    5. Go to http://localhost:8000 in your browser and check that everything looks/works ok.
  4. Push to your forked repo and make a PR.
Clone this wiki locally