feature/add separate documentation page

.gitignore

@@ -4,4 +4,7 @@
 /build/
 /PAGETools.egg-info/
 /venv/
-/.idea/
+/.idea/
+node_modules/
+.DS_Store
+cache

docs/.vitepress/config.mts

@@ -0,0 +1,64 @@
+import { defineConfig } from 'vitepress'
+
+// https://vitepress.dev/reference/site-config
+export default defineConfig({
+  title: "PAGETools",
+  description: "Documentation for the PAGETools python library",
+  themeConfig: {
+    // https://vitepress.dev/reference/default-theme-config
+    nav: [
+      { text: 'Home', link: '/' },
+      { text: 'Installation', link: '/installation' },
+      { text: 'Tools', link: '/tools/index' },
+    ],
+
+    sidebar: [
+      {
+        text: 'Installation', link: '/installation',
+      },
+      {
+        text: 'Tools',
+        items: [
+          {
+            text: "Analytics",
+            items: [
+              {
+               text: "Get Codec", link: "/tools/analytics/get_codec"
+              },
+              {
+               text: "Get Text Count", link: "/tools/analytics/get_text_count"
+              }
+            ]
+          },
+          {
+            text: "Management",
+            items: [
+            ]
+          },
+          {
+            text: "Transformation",
+            items: [
+              {
+               text: "Change Index", link: "/tools/transformation/change_index"
+              },
+              {
+               text: "Extraction", link: "/tools/transformation/extraction"
+              },
+              {
+               text: "Line2Page", link: "/tools/transformation/line2page"
+              },
+              {
+               text: "Regularization", link: "/tools/transformation/regularization"
+              },
+            ]
+          }
+        ]
+      }
+    ],
+
+    socialLinks: [
+      { icon: 'github', link: 'https://github.com/uniwue-zpd/PAGETools' },
+      { icon: 'twitter', link: 'https://twitter.com/uniwue_zpd' }
+    ]
+  }
+})

docs/.vitepress/theme/index.ts

@@ -0,0 +1,17 @@
+// https://vitepress.dev/guide/custom-theme
+import { h } from 'vue'
+import type { Theme } from 'vitepress'
+import DefaultTheme from 'vitepress/theme'
+import './style.css'
+
+export default {
+  extends: DefaultTheme,
+  Layout: () => {
+    return h(DefaultTheme.Layout, null, {
+      // https://vitepress.dev/guide/extending-default-theme#layout-slots
+    })
+  },
+  enhanceApp({ app, router, siteData }) {
+    // ...
+  }
+} satisfies Theme

docs/.vitepress/theme/style.css

@@ -0,0 +1,139 @@
+/**
+ * Customize default theme styling by overriding CSS variables:
+ * https://github.com/vuejs/vitepress/blob/main/src/client/theme-default/styles/vars.css
+ */
+
+/**
+ * Colors
+ *
+ * Each colors have exact same color scale system with 3 levels of solid
+ * colors with different brightness, and 1 soft color.
+ * 
+ * - `XXX-1`: The most solid color used mainly for colored text. It must
+ *   satisfy the contrast ratio against when used on top of `XXX-soft`.
+ *
+ * - `XXX-2`: The color used mainly for hover state of the button.
+ *
+ * - `XXX-3`: The color for solid background, such as bg color of the button.
+ *   It must satisfy the contrast ratio with pure white (#ffffff) text on
+ *   top of it.
+ *
+ * - `XXX-soft`: The color used for subtle background such as custom container
+ *   or badges. It must satisfy the contrast ratio when putting `XXX-1` colors
+ *   on top of it.
+ *
+ *   The soft color must be semi transparent alpha channel. This is crucial
+ *   because it allows adding multiple "soft" colors on top of each other
+ *   to create a accent, such as when having inline code block inside
+ *   custom containers.
+ *
+ * - `default`: The color used purely for subtle indication without any
+ *   special meanings attched to it such as bg color for menu hover state.
+ *
+ * - `brand`: Used for primary brand colors, such as link text, button with
+ *   brand theme, etc.
+ *
+ * - `tip`: Used to indicate useful information. The default theme uses the
+ *   brand color for this by default.
+ *
+ * - `warning`: Used to indicate warning to the users. Used in custom
+ *   container, badges, etc.
+ *
+ * - `danger`: Used to show error, or dangerous message to the users. Used
+ *   in custom container, badges, etc.
+ * -------------------------------------------------------------------------- */
+
+ :root {
+  --vp-c-default-1: var(--vp-c-gray-1);
+  --vp-c-default-2: var(--vp-c-gray-2);
+  --vp-c-default-3: var(--vp-c-gray-3);
+  --vp-c-default-soft: var(--vp-c-gray-soft);
+
+  --vp-c-brand-1: var(--vp-c-indigo-1);
+  --vp-c-brand-2: var(--vp-c-indigo-2);
+  --vp-c-brand-3: var(--vp-c-indigo-3);
+  --vp-c-brand-soft: var(--vp-c-indigo-soft);
+
+  --vp-c-tip-1: var(--vp-c-brand-1);
+  --vp-c-tip-2: var(--vp-c-brand-2);
+  --vp-c-tip-3: var(--vp-c-brand-3);
+  --vp-c-tip-soft: var(--vp-c-brand-soft);
+
+  --vp-c-warning-1: var(--vp-c-yellow-1);
+  --vp-c-warning-2: var(--vp-c-yellow-2);
+  --vp-c-warning-3: var(--vp-c-yellow-3);
+  --vp-c-warning-soft: var(--vp-c-yellow-soft);
+
+  --vp-c-danger-1: var(--vp-c-red-1);
+  --vp-c-danger-2: var(--vp-c-red-2);
+  --vp-c-danger-3: var(--vp-c-red-3);
+  --vp-c-danger-soft: var(--vp-c-red-soft);
+}
+
+/**
+ * Component: Button
+ * -------------------------------------------------------------------------- */
+
+:root {
+  --vp-button-brand-border: transparent;
+  --vp-button-brand-text: var(--vp-c-white);
+  --vp-button-brand-bg: var(--vp-c-brand-3);
+  --vp-button-brand-hover-border: transparent;
+  --vp-button-brand-hover-text: var(--vp-c-white);
+  --vp-button-brand-hover-bg: var(--vp-c-brand-2);
+  --vp-button-brand-active-border: transparent;
+  --vp-button-brand-active-text: var(--vp-c-white);
+  --vp-button-brand-active-bg: var(--vp-c-brand-1);
+}
+
+/**
+ * Component: Home
+ * -------------------------------------------------------------------------- */
+
+:root {
+  --vp-home-hero-name-color: transparent;
+  --vp-home-hero-name-background: -webkit-linear-gradient(
+    120deg,
+    #bd34fe 30%,
+    #41d1ff
+  );
+
+  --vp-home-hero-image-background-image: linear-gradient(
+    -45deg,
+    #bd34fe 50%,
+    #47caff 50%
+  );
+  --vp-home-hero-image-filter: blur(44px);
+}
+
+@media (min-width: 640px) {
+  :root {
+    --vp-home-hero-image-filter: blur(56px);
+  }
+}
+
+@media (min-width: 960px) {
+  :root {
+    --vp-home-hero-image-filter: blur(68px);
+  }
+}
+
+/**
+ * Component: Custom Block
+ * -------------------------------------------------------------------------- */
+
+:root {
+  --vp-custom-block-tip-border: transparent;
+  --vp-custom-block-tip-text: var(--vp-c-text-1);
+  --vp-custom-block-tip-bg: var(--vp-c-brand-soft);
+  --vp-custom-block-tip-code-bg: var(--vp-c-brand-soft);
+}
+
+/**
+ * Component: Algolia
+ * -------------------------------------------------------------------------- */
+
+.DocSearch {
+  --docsearch-primary-color: var(--vp-c-brand-1) !important;
+}
+

docs/index.md

@@ -0,0 +1,25 @@
+---
+# https://vitepress.dev/reference/default-theme-home-page
+layout: home
+
+hero:
+  name: "PAGETools"
+  text: "Python powered PAGE XML toolkit"
+  tagline: 
+  actions:
+    - theme: brand
+      text: Installation
+      link: /installation
+    - theme: alt
+      text: Tools
+      link: /tools
+
+features:
+  - title: Analytics
+    details: Analyze your PAGE XML datasets regarding various metrics
+  - title: Management
+    details: Easily manage your PAGE XML dataset through the CLI 
+  - title: Transformations
+    details: Extract data from your existing PAGE files, generate new PAGE XML datasets and much more 
+---
+

docs/installation.md

@@ -0,0 +1,16 @@
+## Installation
+### Installation using pip
+The suggested method is to install `pagetools` into a virtual environment using pip:
+```bash
+python -m venv VENV_NAME
+source VENV_NAME/bin/activate
+pip install pagetools
+```
+To install the package from source, clone this repository and run inside the project directory
+```bash
+git clone https://github.com/uniwue-zpd/PAGETools
+cd PAGETools
+python -m venv VENV_NAME
+source VENV_NAME/bin/activate
+pip install .
+```

docs/package.json

@@ -0,0 +1,11 @@
+{
+  "scripts": {
+    "docs:dev": "vitepress dev",
+    "docs:build": "vitepress build",
+    "docs:preview": "vitepress preview"
+  },
+  "devDependencies": {
+    "vitepress": "^1.0.0-rc.29",
+    "vue": "^3.3.8"
+  }
+}

docs/tools/analytics/get_codec.md

@@ -0,0 +1,33 @@
+# Get Codec
+## Usage
+```
+Usage: pagetools get-codec [OPTIONS] FILES...
+
+  Retrieves codec of PAGE XML files.
+
+Options:
+  -l, --level [region|line|word|glyph]
+                                  [default: line]
+  -idx, --index INTEGER           Considers only text from TextEquiv elements
+                                  with a certain index.
+  -mc, --most-common INTEGER      Only prints n most common entries. Shows all
+                                  by default.
+  -o, --output TEXT               File to which results are written.
+  -rw, --remove-whitespace
+  -of, --output-format [json|csv|txt]
+                                  Available result formats.
+  -freq, --frequencies            Outputs character frequencies.
+  -nu, --normalize-unicode [NFC|NFD|NFKC|NFKD]
+                                  Normalize unicode for both rules and PAGE
+                                  XML tests.
+  --text-output-newline           Inserts new line after every character in
+                                  txt output. Only applies when frequencies
+                                  aren't output.
+  --verbose / --silent            Choose between verbose or silent output.
+  --help                          Show this message and exit.
+```
+
+## Example
+::: info
+TODO
+:::

docs/tools/analytics/get_text_count.md

@@ -0,0 +1,20 @@
+# Get Text Count
+## Usage
+```
+Usage: pagetools get-text-count [OPTIONS] FILES...
+
+  Returns the amount of text equiv elements in certain elements for certain
+  indices.
+
+Options:
+  -e, --element [TextRegion|TextLine|Word]
+  -i, --index TEXT                [required]
+  -so, --stats-out TEXT           Output directory for detailed stats csv
+                                  file.
+  --help                          Show this message and exit.
+
+```
+## Example
+::: info
+TODO
+:::

docs/tools/index.md

@@ -0,0 +1,13 @@
+# Tools
+## Analytics
+- [Get Codec](/tools/analytics/get_codec): Get overview of all used characters (codec) in a data set
+- [Get Text Count](/tools/analytics/get_text_count): Get overview of text contained in data set
+## Management
+:::info
+TODO
+:::
+## Transformation
+- [Change Index](/tools/analytics/get_codec): Change index of elements
+- [Extraction](/tools/analytics/get_codec): Extract elements as images and optionally their text content
+- [Line2Page](/tools/analytics/get_codec): Merges line images and line texts into combined images and PAGE XML files
+- [Regularization](/tools/analytics/get_codec): Regularize the text content of PAGE XML files using custom rulesets. 

docs/tools/transformation/change_index.md

@@ -0,0 +1,16 @@
+# Change Index
+## Usage
+```
+Usage: pagetools change-index [OPTIONS] XMLS... SOURCE TARGET
+
+  Change index on TextEquiv elements.
+
+Options:
+  -s, --safe / -us, --unsafe  Creates backups of original files before
+                              overwriting.
+  --help                      Show this message and exit.
+```
+## Example
+::: info
+TODO
+:::