Documentation updates

modules/microsite/docs/doc/install.md

@@ -57,7 +57,7 @@ build using JDK 8. But a later version of Java should work as well.
 The next tools are only required on machines running the *Joex*
 component.
 
-### External Tools for Joex
+### External Programs for Joex
 
 - [Ghostscript](http://pages.cs.wisc.edu/~ghost/) (the `gs` command)
   is used to extract/convert PDF files into images that are then fed

modules/microsite/docs/doc/tools.md

@@ -9,183 +9,10 @@ permalink: doc/tools
 The `tools/` folder contains some scripts and other resources intented
 for integrating docspell.
 
-## consumedir
+- [ds.sh](ds) A script to quickly upload files from the command
-
+  line.
-The `consumerdir.sh` is a bash script that works in two modes:
+- [Consume Directory](consumedir) A script to watch a directory
-
+  for new files and upload them to docspell.
-- Go through all files in given directories (non recursively) and sent
+- [Browser Extension](browserext) An extension for firefox to
-  each to docspell.
+  upload files from your browser via *right-click -> upload to
-- Watch one or more directories for new files and upload them to
+  docspell*.
-  docspell.
-
-It can watch or go through one or more directories. Files can be
-uploaded to multiple urls.
-
-Run the script with the `-h` option, to see a short help text. The
-help text will also show the values for any given option.
-
-The script requires `curl` for uploading. It requires the
-`inotifywait` command if directories should be watched for new
-files. If the `-m` option is used, the script will skip duplicate
-files. For this the `sha256sum` command is required.
-
-Example for watching two directories:
-
-``` bash
-./tools/consumedir.sh --path ~/Downloads --path ~/pdfs -m -dv http://localhost:7880/api/v1/open/upload/item/5DxhjkvWf9S-CkWqF3Kr892-WgoCspFWDo7-XBykwCyAUxQ
-```
-
-The script by default watches the given directories. If the `-o`
-option is used, it will instead go through these directories and
-upload all pdf files in there.
-
-Example for uploading all immediatly (the same as above only with `-o`
-added):
-
-``` bash
-./tools/consumedir.sh -o --path ~/Downloads --path ~/pdfs/ -m -dv http://localhost:7880/api/v1/open/upload/item/5DxhjkvWf9S-CkWqF3Kr892-WgoCspFWDo7-XBykwCyAUxQ
-```
-
-
-### Systemd
-
-The script can be used with systemd to run as a service. This is an
-example unit file:
-
-```
-[Unit]
-After=networking.target
-Description=Docspell Consumedir
-
-[Service]
-Environment="PATH=/set/a/path"
-
-ExecStart=/bin/su -s /bin/bash someuser -c "consumedir.sh --path '/a/path/' -m 'http://localhost:7880/api/v1/open/upload/item/5DxhjkvWf9S-CkWqF3Kr892-WgoCspFWDo7-XBykwCyAUxQ'"
-```
-
-This unit file is just an example, it needs some fiddling. It assumes
-an existing user `someuser` that is used to run this service. The url
-`http://localhost:7880/api/v1/open/upload/...` is an anonymous upload
-url as described [here](./uploading#anonymous-upload).
-
-
-## ds.sh
-
-A bash script to quickly upload files from the command line. It reads
-a configuration file containing the URLs to upload to. Then each file
-given to the script will be uploaded to al URLs in the config.
-
-The config file is expected in
-`$XDG_CONFIG_HOME/docspell/ds.conf`. `$XDG_CONFIG_HOME` defaults to
-`~/.config`.
-
-The config file contains lines with key-value pairs, separated by a
-`=` sign. Lines starting with `#` are ignored. Example:
-
-```
-# Config file
-url.1 = http://localhost:7880/api/v1/open/upload/item/5DxhjkvWf9S-CkWqF3Kr892-WgoCspFWDo7-XBykwCyAUxQ
-url.2 = http://localhost:7880/api/v1/open/upload/item/6DxhjkvWf9S-CkWqF3Kr892-WgoCspFWDo7-XBykwCyAUxQ
-```
-
-The key must start with `url`. The urls should be [anonymous upload
-urls](./uploading#anonymous-upload).
-
-
-### Usage
-
-- The `-c` option allows to specifiy a different config file.
-- The `-h` option shows a help overview.
-- The `-d` option deletes files after upload was successful
-- The `-e` option can be used to check for file existence in docspell.
-  Instead of uploading, the script only checks whether the file is in
-  docspell or not.
-
-The script takes a list of files as arguments.
-
-
-Example:
-
-``` bash
-./ds.sh ~/Downloads/*.pdf
-```
-
-
-## Webextension for Docspell
-
-Idea: Inside the browser click on a PDF and send it to docspell. It is
-downloaded in the context of your current page. Then handed to an
-application that pushes it to docspell. There is a browser add-on
-implementing this in `tools/webextension`. This add-on only works with
-firefox.
-
-### Install
-
-This is a bit complicated, since you need to install external tools
-and the web extension. Both work together.
-
-#### Install `ds.sh`
-
-First copy the `ds.sh` tool somewhere in your `PATH`, maybe
-`/usr/local/bin` as described above.
-
-
-#### Install the native part
-
-Then install the "native" part of the web extension:
-
-Copy or symlink the `native.py` script into some known location. For
-example:
-
-``` bash
-ln -s ~/docspell-checkout/tools/webextension/native/native.py /usr/local/share/docspell/native.py
-```
-
-Then copy the `app_manifest.json` to
-`$HOME/.mozilla/native-messaging-hosts/docspell.json`. For example:
-
-``` bash
-cp ~/docspell-checkout/tools/webextension/native/app_manifest.json  ~/.mozilla/native-messaging-hosts/docspell.json
-```
-
-See
-[here](https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/Native_manifests#Manifest_location)
-for details.
-
-And you might want to modify this json file, so the path to the
-`native.py` script is correct (it must be absolute).
-
-If the `ds.sh` script is in your `$PATH`, then this should
-work. Otherwise, edit the `native.py` script and change the path to
-the tool. Or create a file `$HOME/.config/docspell/ds.cmd` whose
-content is the path to the `ds.sh` script.
-
-
-#### Install the extension
-
-An extension file can be build using the `make-xpi.sh` script. But
-installing it in "standard" firefox won't work, because [Mozilla
-requires extensions to be signed by
-them](https://wiki.mozilla.org/Add-ons/Extension_Signing). This means
-creating an account and going through some process…. So here are two
-alternatives:
-
-1. Open firefox and type `about:debugging` in the addressbar. Then
-   click on *'Load Temporary Add-on...'* and select the
-   `manifest.json` file. The extension is now installed. The downside
-   is, that the extension will be removed once firefox is closed.
-2. Use Firefox ESR, which allows to install Add-ons not signed by
-   Mozilla. But it has to be configured: Open firefox and type
-   `about:config` in the address bar. Search for key
-   `xpinstall.signatures.required` and set it to `false`. This is
-   described on the last paragraph on [this
-   page](https://support.mozilla.org/en-US/kb/add-on-signing-in-firefox).
-
-When you right click on a file link, there should be a context menu
-entry *'Docspell Upload Helper'*. The add-on will download this file
-using the browser and then send the file path to the `native.py`
-script. This script will in turn call `ds.sh` which finally uploads it
-to your configured URLs.
-
-Open the Add-ons page (`Ctrl`+`Shift`+`A`), the new add-on should be
-there.

modules/microsite/docs/doc/tools/browserext.md

@@ -0,0 +1,84 @@
+---
+layout: docs
+title: Browser Extension (Firefox)
+permalink: doc/tools/browserext
+---
+
+# {{ page.title }}
+
+The idea is to click on a file in firefox and send it to docspell. It
+is downloaded in the context of your current page. Then handed to an
+application that pushes it to docspell. There is a browser add-on
+implementing this in `tools/webextension`. This add-on only works with
+firefox.
+
+### Install
+
+This is a bit complicated, since you need to install external tools
+and the web extension. Both work together.
+
+#### Install `ds.sh`
+
+First copy the `ds.sh` tool somewhere in your `PATH`, maybe
+`/usr/local/bin` as described above.
+
+
+#### Install the native part
+
+Then install the "native" part of the web extension:
+
+Copy or symlink the `native.py` script into some known location. For
+example:
+
+``` bash
+ln -s ~/docspell-checkout/tools/webextension/native/native.py /usr/local/share/docspell/native.py
+```
+
+Then copy the `app_manifest.json` to
+`$HOME/.mozilla/native-messaging-hosts/docspell.json`. For example:
+
+``` bash
+cp ~/docspell-checkout/tools/webextension/native/app_manifest.json  ~/.mozilla/native-messaging-hosts/docspell.json
+```
+
+See
+[here](https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/Native_manifests#Manifest_location)
+for details.
+
+And you might want to modify this json file, so the path to the
+`native.py` script is correct (it must be absolute).
+
+If the `ds.sh` script is in your `$PATH`, then this should
+work. Otherwise, edit the `native.py` script and change the path to
+the tool. Or create a file `$HOME/.config/docspell/ds.cmd` whose
+content is the path to the `ds.sh` script.
+
+
+#### Install the extension
+
+An extension file can be build using the `make-xpi.sh` script. But
+installing it in "standard" firefox won't work, because [Mozilla
+requires extensions to be signed by
+them](https://wiki.mozilla.org/Add-ons/Extension_Signing). This means
+creating an account and going through some process…. So here are two
+alternatives:
+
+1. Open firefox and type `about:debugging` in the addressbar. Then
+   click on *'Load Temporary Add-on...'* and select the
+   `manifest.json` file. The extension is now installed. The downside
+   is, that the extension will be removed once firefox is closed.
+2. Use Firefox ESR, which allows to install Add-ons not signed by
+   Mozilla. But it has to be configured: Open firefox and type
+   `about:config` in the address bar. Search for key
+   `xpinstall.signatures.required` and set it to `false`. This is
+   described on the last paragraph on [this
+   page](https://support.mozilla.org/en-US/kb/add-on-signing-in-firefox).
+
+When you right click on a file link, there should be a context menu
+entry *'Docspell Upload Helper'*. The add-on will download this file
+using the browser and then send the file path to the `native.py`
+script. This script will in turn call `ds.sh` which finally uploads it
+to your configured URLs.
+
+Open the Add-ons page (`Ctrl`+`Shift`+`A`), the new add-on should be
+there.

modules/microsite/docs/doc/tools/consumedir.md

@@ -0,0 +1,64 @@
+---
+layout: docs
+title: Consume Directory
+permalink: doc/tools/consumedir
+---
+
+# {{ page.title }}
+
+The `consumerdir.sh` is a bash script that works in two modes:
+
+- Go through all files in given directories (non recursively) and sent
+  each to docspell.
+- Watch one or more directories for new files and upload them to
+  docspell.
+
+It can watch or go through one or more directories. Files can be
+uploaded to multiple urls.
+
+Run the script with the `-h` option, to see a short help text. The
+help text will also show the values for any given option.
+
+The script requires `curl` for uploading. It requires the
+`inotifywait` command if directories should be watched for new
+files. If the `-m` option is used, the script will skip duplicate
+files. For this the `sha256sum` command is required.
+
+Example for watching two directories:
+
+``` bash
+./tools/consumedir.sh --path ~/Downloads --path ~/pdfs -m -dv http://localhost:7880/api/v1/open/upload/item/5DxhjkvWf9S-CkWqF3Kr892-WgoCspFWDo7-XBykwCyAUxQ
+```
+
+The script by default watches the given directories. If the `-o`
+option is used, it will instead go through these directories and
+upload all files in there.
+
+Example for uploading all immediatly (the same as above only with `-o`
+added):
+
+``` bash
+./tools/consumedir.sh -o --path ~/Downloads --path ~/pdfs/ -m -dv http://localhost:7880/api/v1/open/upload/item/5DxhjkvWf9S-CkWqF3Kr892-WgoCspFWDo7-XBykwCyAUxQ
+```
+
+
+## Systemd
+
+The script can be used with systemd to run as a service. This is an
+example unit file:
+
+```
+[Unit]
+After=networking.target
+Description=Docspell Consumedir
+
+[Service]
+Environment="PATH=/set/a/path"
+
+ExecStart=/bin/su -s /bin/bash someuser -c "consumedir.sh --path '/a/path/' -m 'http://localhost:7880/api/v1/open/upload/item/5DxhjkvWf9S-CkWqF3Kr892-WgoCspFWDo7-XBykwCyAUxQ'"
+```
+
+This unit file is just an example, it needs some fiddling. It assumes
+an existing user `someuser` that is used to run this service. The url
+`http://localhost:7880/api/v1/open/upload/...` is an anonymous upload
+url as described [here](../uploading#anonymous-upload).

modules/microsite/docs/doc/tools/ds.md

@@ -0,0 +1,47 @@
+---
+layout: docs
+title: Upload CLI
+permalink: doc/tools/ds
+---
+
+# {{ page.title }}
+
+A bash script is provided to quickly upload files from the command
+line. It reads a configuration file containing the URLs to upload to.
+Then each file given to the script will be uploaded to al URLs in the
+config.
+
+The config file is expected in
+`$XDG_CONFIG_HOME/docspell/ds.conf`. `$XDG_CONFIG_HOME` defaults to
+`~/.config`.
+
+The config file contains lines with key-value pairs, separated by a
+`=` sign. Lines starting with `#` are ignored. Example:
+
+```
+# Config file
+url.1 = http://localhost:7880/api/v1/open/upload/item/5DxhjkvWf9S-CkWqF3Kr892-WgoCspFWDo7-XBykwCyAUxQ
+url.2 = http://localhost:7880/api/v1/open/upload/item/6DxhjkvWf9S-CkWqF3Kr892-WgoCspFWDo7-XBykwCyAUxQ
+```
+
+The key must start with `url`. The urls should be [anonymous upload
+urls](./uploading#anonymous-upload).
+
+
+### Usage
+
+- The `-c` option allows to specifiy a different config file.
+- The `-h` option shows a help overview.
+- The `-d` option deletes files after upload was successful
+- The `-e` option can be used to check for file existence in docspell.
+  Instead of uploading, the script only checks whether the file is in
+  docspell or not.
+
+The script takes a list of files as arguments.
+
+
+Example:
+
+``` bash
+./ds.sh ~/Downloads/*.pdf
+```

modules/microsite/docs/features.md

@@ -42,9 +42,11 @@ permalink: features
     - [eml](https://en.wikipedia.org/wiki/Email#Filename_extensions)
       (e-mail files in plain text MIME)
 - [Tooling](doc/tools):
-  - Watch a folder: watch folders for changes and send files to docspell
+  - [Watch a folder](doc/tools/consumedir): watch folders for changes
-  - Firefox plugin: right click on a link and send the file to docspell
+    and send files to docspell
-  - Simple CLI for uploading files
+  - [Simple CLI for uploading files](doc/tools/ds)
+  - [Firefox plugin](doc/tools/browserext): right click on a link and
+    send the file to docspell
 - License: GPLv3
 
 

modules/microsite/docs/getit.md

@@ -11,8 +11,20 @@ Page](https://github.com/eikek/docspell/releases). There are `deb`
 packages and generic zip files. Alternatively, docspell can be
 installed via [nix](doc/nix) or docker (see below).
 
+There are the following quick ways to get docspell to run on your
+machine:
 
-## Prerequisite
+- [Download, Unpack, Run](#without-docker)
+- [With Docker](#with-docker)
+- [NixOs Module](doc/nix#docspell-as-a-service-on-nixos)
+
+Check the [early demo video](demo) to see the basic idea. Refer to the
+[documentation](doc) for more information on how to use docspell.
+
+
+## Without Docker
+
+### Prerequisite
 
 Install Java (use your package manager or look
 [here](https://adoptopenjdk.net/)).
@@ -31,7 +43,7 @@ PDF conversion requires the following tools:
 - [wkhtmltopdf](https://wkhtmltopdf.org/)
 
 
-## Using zip files
+### Using zip files
 
 You need to download the two files:
 
@@ -57,11 +69,8 @@ You need to download the two files:
 4. Point your browser to: <http://localhost:7880/app>
 5. Register a new account, sign in and try it.
 
-Check the [early demo video](demo) to see the basic idea. Refer to the
-[documentation](doc) for more information on how to use docspell.
 
-
+## With Docker
-## Docker
 
 There is a [docker-compose](https://docs.docker.com/compose/) setup
 available in the `/docker` folder.
@@ -81,4 +90,4 @@ available in the `/docker` folder.
 4. Goto <http://localhost:7880>, signup and login
 
 The directory contains a file `docspell.conf` that you can
-[modify](configure) as needed.
+[modify](doc/configure) as needed.

modules/microsite/src/main/resources/microsite/data/menu.yml

@@ -57,6 +57,16 @@ options:
   - title: Tools
     url: doc/tools
 
+    nested_options:
+      - title: Upload CLI
+        url: doc/tools/ds
+
+      - title: Consume Directory
+        url: doc/tools/consumedir
+
+      - title: Browser Extension (Firefox)
+        url: doc/tools/browserext
+
   - title: Development
     url: dev