feat/documentation site (evan-buss#105)

* feat(docs): scaffold new mkdocs site

- copy over sections of the readme
- set up github actions workflow to publish to github pages on change.

* fix(docs): use new github pages actions instead of separate branch

* fix(docs): allow manual workflow dispatch?

* fix(docs): change file to trigger publish

* fix(docs): invalid requirements path

* fix(docs): use absolute path?

* fix(ci): don't run docker build on doc changes

.devcontainer/devcontainer.json

@@ -16,7 +16,7 @@
   },
   "customizations": {
     "vscode": {
-      "extensions": ["golang.go", "heybourn.headwind", "esbenp.prettier-vscode", "bradlc.vscode-tailwindcss", "ms-vscode.makefile-tools"]
+      "extensions": ["golang.go", "heybourn.headwind", "esbenp.prettier-vscode", "bradlc.vscode-tailwindcss", "ms-vscode.makefile-tools", "redhat.vscode-yaml"]
     }
   }
 }

.devcontainer/setup.sh

@@ -1,3 +1,6 @@
 #!/bin/bash
 
-go install github.com/go-task/task/v3/cmd/task@latest
+go install github.com/go-task/task/v3/cmd/task@latest
+
+sudo apt update
+sudo apt install python3.10-venv

.github/workflows/docker_hub.yml

@@ -10,8 +10,10 @@ on:
     branches:
       - master
       - development
+    paths-ignore:
+      - "docs/**"
     tags:
-      - 'v*.*.*'
+      - "v*.*.*"
 
 jobs:
   build:
@@ -37,7 +39,7 @@ jobs:
           tags: |
             type=semver,pattern={{version}}
             type=edge,branch=development
-            
+
       - name: Set up QEMU
         uses: docker/setup-qemu-action@v2
 
@@ -51,8 +53,8 @@ jobs:
       - name: Login to Docker Hub
         uses: docker/login-action@v2
         with:
-            username: ${{ secrets.DOCKER_USERNAME }}
-            password: ${{ secrets.DOCKER_HUB_TOKEN }}
+          username: ${{ secrets.DOCKER_USERNAME }}
+          password: ${{ secrets.DOCKER_HUB_TOKEN }}
 
       - name: Build and Push
         uses: docker/build-push-action@v3

.github/workflows/docs.yml

@@ -0,0 +1,53 @@
+# Simple workflow for deploying static content to GitHub Pages
+name: Deploy static content to Pages
+
+on:
+  workflow_dispatch:
+  # Runs on pushes targeting the default branch
+  push:
+    paths:
+      - "docs/**"
+
+defaults:
+  run:
+    shell: bash
+    working-directory: docs
+
+# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# Allow one concurrent deployment
+concurrency:
+  group: "pages"
+  cancel-in-progress: true
+
+jobs:
+  # Single deploy job since we're just deploying
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v3
+      - name: Setup Pages
+        uses: actions/configure-pages@v2
+      - name: Set up Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: "3.10"
+      - name: Build MkDocs Site
+        run: |
+          pip install -r requirements.txt
+          mkdocs build
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v1
+        with:
+          path: "docs/site/"
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v1

.github/workflows/release.yml

@@ -18,16 +18,19 @@ jobs:
 
       - uses: actions/setup-go@v2
         with:
-          go-version: "^1.17.0"
+          go-version: "^1.19.2"
       - run: go version
-    
+
       - name: Setup Node.js
         uses: actions/setup-node@v3
         with:
-          node-version: 16
+          node-version: 18
+
+      - name: Install Task
+        uses: arduino/setup-task@v1
 
       - name: Build
-        run: ./build.sh
+        run: task release:build
 
       - name: Create Release
         uses: softprops/action-gh-release@v1
@@ -38,4 +41,4 @@ jobs:
           fail_on_unmatched_files: true
           name: Release ${{ github.ref }}
           files: |
-            ./build/*
+            ./build/*

.gitignore

@@ -5,6 +5,8 @@ openbooks
 *.DS_Store
 **/dist
 .task/
+docs/venv/
+docs/site/
 # end persist
 
 

.vscode/settings.json

@@ -0,0 +1,5 @@
+{
+  "yaml.schemas": {
+    "https://squidfunk.github.io/mkdocs-material/schema.json": "mkdocs.yml"
+  }
+}

Taskfile.Documentation.yaml

@@ -0,0 +1,16 @@
+# https://taskfile.dev
+
+version: "3"
+
+tasks:
+  init:
+    dir: docs
+    cmds:
+      - python3 -m venv venv
+      - source ./venv/bin/activate
+      - pip3 install -r requirements.txt
+
+  serve:
+    dir: docs
+    cmds:
+      - mkdocs serve

Taskfile.Release.yaml

@@ -12,9 +12,11 @@ tasks:
 
   build:
     desc: Build OpenBooks binaries for all supported platforms.
+    deps:
+      - npm-build
     dir: cmd/openbooks
     cmds:
-      - go get ./..
+      - go get
       - env CGO_ENABLED=0 GOOS=windows GOARCH=amd64 go build -o ./../../build/openbooks.exe
       - env CGO_ENABLED=0 GOOS=darwin GOARCH=amd64 go build -o ./../../build/openbooks_mac
       - env CGO_ENABLED=0 GOOS=darwin GOARCH=arm64 go build -o ./../../build/openbooks_mac_arm

Taskfile.yaml

@@ -4,4 +4,5 @@ version: "3"
 
 includes:
   dev: Taskfile.Development.yaml
+  docs: Taskfile.Documentation.yaml
   release: Taskfile.Release.yaml

docs/docs/developers/index.md

@@ -0,0 +1,55 @@
+### Install the dependencies
+
+- `go get`
+- `cd server/app && npm install`
+- `cd ../..`
+- `go run main.go`
+
+### Build the React SPA and compile binaries for multiple platforms.
+
+- Run `./build.sh`
+- This will install npm packages, build the React app, and compile the executable.
+
+### Build the go binary (if you haven't changed the frontend)
+
+- `go build`
+
+### Mock Development Server
+
+- The mock server allows you to debug responses and requests to simplified IRC / DCC
+  servers that mimic the responses received from IRC Highway.
+- ```bash
+  cd cmd/mock_server
+  go run .
+  # Another Terminal
+  cd cmd/openbooks
+  go run . server --server localhost --log
+  ```
+
+### Desktop App
+
+Compile OpenBooks with experimental webview support:
+
+```shell
+cd cmd/openbooks
+go build -tags webview
+```
+
+## Why / How
+
+- I wrote this as an easier way to search and download books from irchighway.net. It handles all the extraction and data processing for you. You just have to click the book you want. Hopefully you find it much easier than the IRC interface.
+- It was also interesting to learn how the [IRC](https://en.wikipedia.org/wiki/Internet_Relay_Chat) and [DCC](https://en.wikipedia.org/wiki/Direct_Client-to-Client) protocols work and write custom implementations.
+
+## Technology
+
+- Backend
+  - Golang
+  - Chi
+  - gorilla/websocket
+  - Archiver (extract files from various archive formats)
+- Frontend
+  - React.js
+  - TypeScript
+  - Redux / Redux Toolkit
+  - Mantine UI / @emotion/react
+  - Framer Motion

docs/docs/getting-started.md

@@ -0,0 +1,33 @@
+### Binary
+
+1. Download the latest release for your platform from the [releases page](https://github.com/evan-buss/openbooks/releases).
+2. Run the binary
+   - Linux users may have to run `chmod +x [binary name]` to make it executable
+3. `./openbooks --help`
+   - This will display all possible configuration values and introduce the two modes; CLI or Server.
+
+### Docker
+
+- Basic config
+  - `docker run -p 8080:80 evanbuss/openbooks`
+- Config to persist all eBook files to disk
+  - `docker run -p 8080:80 -v /home/evan/Downloads/openbooks:/books evanbuss/openbooks --persist`
+
+### Setting the Base Path
+
+OpenBooks server doesn't have to be hosted at the root of your webserver. The basepath value allows you to host it behind a reverse proxy. The base path value must have opening and closing forward slashes (default "/").
+
+- Docker
+  - `docker run -p 8080:80 -e BASE_PATH=/openbooks/ evanbuss/openbooks`
+- Binary
+  - `./openbooks server --basepath /openbooks/`
+
+## Usage
+
+For a complete list of features use the `--help` flags on all subcommands.
+For example `openbooks cli --help or openbooks cli download --help`. There are
+two modes; Server or CLI. In CLI mode you interact and download books through
+a terminal interface. In server mode the application runs as a web application
+that you can visit in your browser.
+
+Double clicking the executable will open the UI in your browser. In the future it may use [webviews](https://developer.microsoft.com/en-us/microsoft-edge/webview2/) to provide a "native-like" desktop application.

docs/docs/index.md

@@ -0,0 +1,12 @@
+# OpenBooks
+
+![OpenBooks Light Mode](https://github.com/evan-buss/openbooks/blob/master/.github/home_v3.png?raw=true#only-light)
+![OpenBooks Dark Mode](https://github.com/evan-buss/openbooks/blob/master/.github/home_v3_dark.png?raw=true#only-dark)
+
+> NOTE: Going forward only the latest release will be supported. If you encounter any issues, be sure you are using the latest version.
+
+[![Docker Pulls](https://img.shields.io/docker/pulls/evanbuss/openbooks.svg)](https://hub.docker.com/r/evanbuss/openbooks/)
+
+Openbooks allows you to download ebooks from irc.irchighway.net quickly and easily.
+
+test

docs/mkdocs.yml

@@ -0,0 +1,43 @@
+site_name: OpenBooks
+repo_name: OpenBooks
+repo_url: https://github.com/evan-buss/openbooks
+
+markdown_extensions:
+  - attr_list
+  - md_in_html
+
+theme:
+  name: material
+  features:
+    - navigation.instant
+    - navigation.tabs
+    # - navigation.tabs.sticky
+    - navigation.indexes
+  font:
+    text: Inter
+  icon:
+    logo: fontawesome/solid/book-open
+    repo: fontawesome/brands/github
+
+  palette:
+    # Palette toggle for light mode
+    - scheme: default
+      primary: blue
+      accent: cyan
+      toggle:
+        icon: material/brightness-7
+        name: Switch to dark mode
+
+    # Palette toggle for dark mode
+    - scheme: slate
+      primary: blue
+      accent: cyan
+      toggle:
+        icon: material/brightness-4
+        name: Switch to light mode
+
+nav:
+  - Home:
+      - Home: index.md
+      - Getting Started: getting-started.md
+  - Developers: developers/index.md

docs/requirements.txt

@@ -0,0 +1,23 @@
+certifi==2022.9.24
+charset-normalizer==2.1.1
+click==8.1.3
+ghp-import==2.1.0
+idna==3.4
+Jinja2==3.1.2
+Markdown==3.3.7
+MarkupSafe==2.1.1
+mergedeep==1.3.4
+mkdocs==1.4.1
+mkdocs-material==8.5.7
+mkdocs-material-extensions==1.1
+packaging==21.3
+Pygments==2.13.0
+pymdown-extensions==9.7
+pyparsing==3.0.9
+python-dateutil==2.8.2
+PyYAML==6.0
+pyyaml_env_tag==0.1
+requests==2.28.1
+six==1.16.0
+urllib3==1.26.12
+watchdog==2.1.9