🧑‍⚕️ User Docs (#80)

* Initial docs

* Copy docs infrastructure from ov-deploy

* Updates required python to 3.9

* Splits lockfile into docs, prod

* Ignores local docs site files

---------

Co-authored-by: Andrew Myers <[email protected]>

.github/workflows/docs.yml

@@ -0,0 +1,15 @@
+name: 📖 Docs
+
+on:
+  push:
+    branches:
+      - main
+      - docs
+  workflow_dispatch:
+
+jobs:
+  build:
+    name: 📓 Build and deploy docs
+    uses: WGBH-MLA/.github/.github/workflows/docs.yml@main
+    with:
+      pdm_args: -G docs --no-default -L pdm-locks/pdm.doc.lock

.gitignore

@@ -27,3 +27,6 @@ __pycache__
 .vscode/
 !.vscode/settings.json
 !.vscode/launch.json
+
+# Docs
+site/

docs/index.md

@@ -0,0 +1,19 @@
+# OV-Wag
+
+Wagtail Backend for Open Vault Redesign
+
+## Reference
+
+Further details can be found in the [reference section](reference/index.md)
+
+## Other Resources
+
+This is one componenet of the Open Vault redesign. Others are:
+
+- [ov-frontend](https://github.com/WGBH-MLA/ov-frontend) Frontend
+- [ov-deploy](https://github.com/WGBH-MLA/ov-deploy) Deployment resources
+    - [Documentation](https://wgbh-mla.github.io/ov-deploy/)
+
+## Credits
+
+Created by [WGBH-MLA](https://github.com/WGBH-MLA/)

docs/overrides/main.html

@@ -0,0 +1,8 @@
+{% extends "base.html" %}
+
+{% block outdated %}
+  You're not viewing the latest version.
+  <a href="{{ '../' ~ base_url }}">
+    <strong>Click here to go to latest.</strong>
+  </a>
+{% endblock %}

docs/reference/index.md

@@ -0,0 +1 @@
+# Reference

docs/style/auth.css

@@ -0,0 +1,17 @@
+:root {
+  --md-admonition-icon--auth: url('data:image/svg+xml;charset=utf-8,<svg xmlns="http://www.w3.org/2000/svg" aria-hidden="true" role="img" width="1em" height="1em" preserveAspectRatio="xMidYMid meet" viewBox="0 0 24 24"><path fill="currentColor" d="M8 9a2 2 0 0 1 2 2a2 2 0 0 1-2 2a2 2 0 0 1-2-2a2 2 0 0 1 2-2m4 8H4v-1c0-1.33 2.67-2 4-2s4 .67 4 2v1m8-9h-6v2h6V8m0 4h-6v2h6v-2m0 4h-6v2h6v-2m2-12h-8v2h8v14H2V6h8V4H2a2 2 0 0 0-2 2v14a2 2 0 0 0 2 2h20a2 2 0 0 0 2-2V6a2 2 0 0 0-2-2m-9 2h-2V2h2v4Z"/></svg>');
+}
+.md-typeset .admonition.auth,
+.md-typeset details.auth {
+  border-color: rgb(43, 155, 70);
+}
+.md-typeset .auth > .admonition-title,
+.md-typeset .auth > summary {
+  background-color: rgba(43, 155, 70, 0.1);
+}
+.md-typeset .auth > .admonition-title::before,
+.md-typeset .auth > summary::before {
+  background-color: rgb(43, 155, 70);
+  -webkit-mask-image: var(--md-admonition-icon--auth);
+  mask-image: var(--md-admonition-icon--auth);
+}

docs/style/gbh.css

@@ -0,0 +1,28 @@
+:root {
+  --gbh-xlight-purple: #f2cfff;
+  --gbh-light-purple: #cc8fdf;
+  --gbh-purple: #772b8d;
+  --gbh-dark-purple: #590e6e;
+  --gbh-xdark-purple: #3f0051;
+
+  --gbh-accent-purple: #bc27c7;
+}
+
+[data-md-color-scheme='slate'] {
+  --md-primary-fg-color: var(--gbh-purple);
+  --md-primary-fg-color--light: var(--gbh-light-purple);
+  --md-primary-fg-color--dark: var(--gbh-dark-purple);
+  --md-accent-fg-color: var(--gbh-accent-purple);
+  --md-accent-fg-color--transparent: var(--gbh-accent-purple);
+  --md-accent-bg-color: var(--gbh-accent-purple);
+  --md-accent-bg-color--light: var(--gbh-accent-purple);
+
+  --md-typeset-a-color: var(--gbh-light-purple);
+}
+[data-md-color-scheme='default'] {
+  --md-primary-fg-color: var(--gbh-purple);
+  --md-primary-fg-color--light: var(--gbh-light-purple);
+  --md-primary-fg-color--dark: var(--gbh-dark-purple);
+  --md-accent-fg-color: var(--gbh-accent-purple);
+  --md-accent-fg-color--transparent: var(--gbh-accent-purple);
+}

docs/style/todo.css

@@ -0,0 +1,17 @@
+:root {
+  --md-admonition-icon--todo: url('data:image/svg+xml;charset=utf-8,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512"><!-- Font Awesome Pro 5.15.4 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license (Commercial License) --><path d="M139.61 35.5a12 12 0 0 0-17 0L58.93 98.81l-22.7-22.12a12 12 0 0 0-17 0L3.53 92.41a12 12 0 0 0 0 17l47.59 47.4a12.78 12.78 0 0 0 17.61 0l15.59-15.62L156.52 69a12.09 12.09 0 0 0 .09-17zm0 159.19a12 12 0 0 0-17 0l-63.68 63.72-22.7-22.1a12 12 0 0 0-17 0L3.53 252a12 12 0 0 0 0 17L51 316.5a12.77 12.77 0 0 0 17.6 0l15.7-15.69 72.2-72.22a12 12 0 0 0 .09-16.9zM64 368c-26.49 0-48.59 21.5-48.59 48S37.53 464 64 464a48 48 0 0 0 0-96zm432 16H208a16 16 0 0 0-16 16v32a16 16 0 0 0 16 16h288a16 16 0 0 0 16-16v-32a16 16 0 0 0-16-16zm0-320H208a16 16 0 0 0-16 16v32a16 16 0 0 0 16 16h288a16 16 0 0 0 16-16V80a16 16 0 0 0-16-16zm0 160H208a16 16 0 0 0-16 16v32a16 16 0 0 0 16 16h288a16 16 0 0 0 16-16v-32a16 16 0 0 0-16-16z"/></svg>');
+}
+.md-typeset .admonition.todo,
+.md-typeset details.todo {
+  border-color: rgb(204, 200, 46);
+}
+.md-typeset .todo > .admonition-title,
+.md-typeset .todo > summary {
+  background-color: rgba(204, 200, 46, 0.1);
+}
+.md-typeset .todo > .admonition-title::before,
+.md-typeset .todo > summary::before {
+  background-color: rgb(204, 200, 46);
+  -webkit-mask-image: var(--md-admonition-icon--todo);
+  mask-image: var(--md-admonition-icon--todo);
+}

mkdocs.yml

@@ -0,0 +1,95 @@
+site_name: 'Open Vault: Wagtail'
+site_description: Wagtail backend for Open Vault
+repo_url: https://github.com/WGBH-MLA/ov-wag
+site_url: https://wgbh-mla.github.io/ov-wag/
+edit_uri: ''
+
+markdown_extensions:
+  - admonition
+  - attr_list
+  - def_list
+  - footnotes
+  - md_in_html
+  - meta
+  - pymdownx.caret
+  - pymdownx.details
+  - pymdownx.emoji:
+      emoji_index: !!python/name:material.extensions.emoji.twemoji 
+      emoji_generator: !!python/name:material.extensions.emoji.to_svg
+  - pymdownx.highlight
+  - pymdownx.inlinehilite
+  - pymdownx.keys
+  - pymdownx.mark
+  - pymdownx.snippets
+  - pymdownx.superfences:
+      custom_fences:
+        - name: mermaid
+          class: mermaid
+          format: !!python/name:pymdownx.superfences.fence_code_format
+  - pymdownx.tabbed:
+      alternate_style: true
+  - pymdownx.tasklist:
+      custom_checkbox: true
+  - pymdownx.tilde
+  - pymdownx.inlinehilite
+  - pymdownx.snippets
+  - tables
+  - toc:
+      permalink: true
+      toc_depth: 4
+
+theme:
+  name: material
+  logo: assets/ov-logo.png
+  favicon: assets/ov-favicon.png
+  palette:
+    - media: '(prefers-color-scheme: dark)'
+      scheme: slate
+      toggle:
+        icon: material/lightbulb-outline
+        name: Switch to light mode
+    - media: '(prefers-color-scheme: light)'
+      scheme: default
+      toggle:
+        icon: material/lightbulb-on-outline
+        name: Switch to dark mode
+  features:
+    - content.code.annotate # Enable code annotations for a specific block
+    - header.autohide # Hide header when scrolling
+    - navigation.instant # Load requests with XHR without reloading page
+    - navigation.sections # Top level sections rendered as group in sidebar
+    - navigation.tabs # Top level sections rendered as navbar
+    - navigation.tabs.sticky # Tabs visible on scroll
+    - navigation.top # Back to top button
+    - navigation.tracking # Adds url#anchor to address bar
+    - navigation.expand # Expand all collapsed sections by default
+    - toc.integrate # Nav bar is always rendered on the left
+    - search.highlight # Highlight occurances in result when searching for a term
+    - search.suggest # Suggest results in search
+  custom_dir: docs/overrides
+
+plugins:
+  - search
+  - mkdocstrings
+  - mkdocs-jupyter
+  - git-revision-date-localized:
+      type: timeago
+      enable_creation_date: true
+watch:
+  - docs
+
+extra:
+  social:
+    - name: Open Vault - Demo
+      icon: fontawesome/solid/vault
+      link: http://ovfrontend.k8s.wgbhdigital.org/
+    - name: GitHub repository
+      icon: fontawesome/brands/github
+      link: https://github.com/WGBH-MLA/ov-deploy/
+  version:
+    provider: mike
+
+extra_css:
+  - style/gbh.css
+  - style/auth.css
+  - style/todo.css

overrides/main.html

@@ -0,0 +1,19 @@
+{% extends "base.html" %}
+
+{% block outdated %}
+  You're not viewing the latest version.
+  <a href="{{ '../' ~ base_url }}">
+    <strong>Click here to go to latest.</strong>
+  </a>
+{% endblock %}
+
+
+{% block content %}
+{% if page.nb_url %}
+    <a href="{{ page.nb_url }}" title="Download Notebook" class="md-content__button md-icon">
+        {% include ".icons/material/download.svg" %}
+    </a>
+{% endif %}
+
+{{ super() }}
+{% endblock content %}