Add docs website (#78)

.goreleaser.yml

@@ -5,7 +5,7 @@ before:
   hooks:
     - go mod tidy
     - go generate -x
-    - sh -c "cd ui && npm install && npm run build"
+    - sh -c "cd ui && npm install && npm run build && npm run docs:build"
 builds:
   - env:
       - CGO_ENABLED=0
@@ -18,7 +18,8 @@ builds:
       - goos: windows
         goarch: "386"
     tags:
-      - embedstatic
+      - embedui
+      - embeddocs
       - embedgeo
 dockers:
   - dockerfile: Dockerfile-goreleaser

.vscode/launch.json

@@ -17,7 +17,7 @@
       "request": "launch",
       "mode": "auto",
       "program": "${workspaceFolder}",
-      "buildFlags": "-tags embedstatic"
+      "buildFlags": "-tags embedui"
     }
   ]
 }

Dockerfile

@@ -36,7 +36,7 @@ COPY fonts ./fonts
 COPY data/geo ./data/geo
 # RUN go install -tags libjpeg .
 COPY --from=node-builder /ui/dist/ ./ui/dist
-RUN go install -tags embedstatic,embedgeo .
+RUN go install -tags embedui,embedgeo .
 
 
 

LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2020 Miha Lunar
+Copyright (c) 2020-2023 Miha Lunar
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

README.md

@@ -1,7 +1,7 @@
 <!-- HEADER -->
 <br />
 <p align="center">
-  <a href="https://github.com/othneildrew/Best-README-Template">
+  <a href="https://github.com/smilyorg/photofield">
     <img src="ui/public/android-chrome-192x192.png" alt="Logo" width="80" height="80">
   </a>
 

api.yaml

@@ -671,11 +671,14 @@ components:
       required:
         - search
         - tags
+        - docs
       properties:
         search:
           $ref: "#/components/schemas/Capability"
         tags:
           $ref: "#/components/schemas/Capability"
+        docs:
+          $ref: "#/components/schemas/DocsCapability"
 
     Capability:
       type: object
@@ -684,6 +687,18 @@ components:
       properties:
         supported:
           type: boolean
+
+    DocsCapability:
+      allOf:
+        - $ref: "#/components/schemas/Capability"
+        - type: object
+          required: 
+            - url
+          properties:
+            url:
+              type: string
+              description: URL to the documentation to link to from the UI.
+              default: /docs/usage
 
     Region:
       type: object

embed-docs-stub.go

@@ -0,0 +1,9 @@
+//go:build !embeddocs
+// +build !embeddocs
+
+package main
+
+import "embed"
+
+var StaticDocsFs embed.FS
+var StaticDocsPath = ""

embed-docs.go

@@ -0,0 +1,10 @@
+//go:build embeddocs
+// +build embeddocs
+
+package main
+
+import "embed"
+
+//go:embed ui/docs/.vitepress/dist
+var StaticDocsFs embed.FS
+var StaticDocsPath = "ui/docs/.vitepress/dist"

embed-static-stub.go → embed-ui-stub.go

@@ -1,5 +1,5 @@
-//go:build !embedstatic
-// +build !embedstatic
+//go:build !embedui
+// +build !embedui
 
 package main
 

embed-static.go → embed-ui.go

@@ -1,5 +1,5 @@
-//go:build embedstatic
-// +build embedstatic
+//go:build embedui
+// +build embedui
 
 package main
 

justfile

@@ -9,6 +9,9 @@ build *args:
 build-ui:
   cd ui && npm run build
 
+build-docs:
+  cd ui && npm run docs:build
+
 build-local:
   goreleaser build --snapshot --single-target --clean
 
@@ -28,9 +31,13 @@ release-local:
 run *args: build
   ./photofield {{args}}
 
-run-static *args:
-  go build -tags embedstatic
-  ./photofield {{args}}
+run-embed *args:
+  go build -tags embedui,embeddocs
+  PHOTOFIELD_API_PREFIX="/api" ./photofield {{args}}
+
+run-ui *args:
+  go build -tags embedui
+  PHOTOFIELD_API_PREFIX="/api" ./photofield {{args}}
 
 run-geo *args:
   go build -tags embedgeo

main.go

@@ -643,13 +643,23 @@ func (*Api) PostTasks(w http.ResponseWriter, r *http.Request) {
 }
 
 func (*Api) GetCapabilities(w http.ResponseWriter, r *http.Request) {
+	docsUrl := os.Getenv("PHOTOFIELD_DOCS_URL")
+	if docsUrl == "" {
+		docsUrl = "/docs/usage"
+	}
 	respond(w, r, http.StatusOK, openapi.Capabilities{
 		Search: openapi.Capability{
 			Supported: imageSource.AI.Available(),
 		},
 		Tags: openapi.Capability{
 			Supported: tagsEnabled,
 		},
+		Docs: openapi.DocsCapability{
+			Capability: openapi.Capability{
+				Supported: docsUrl != "",
+			},
+			Url: docsUrl,
+		},
 	})
 }
 
@@ -1449,21 +1459,34 @@ func main() {
 		mime.AddExtensionType(".jpg", "image/jpg")
 		mime.AddExtensionType(".jpeg", "image/jpeg")
 		mime.AddExtensionType(".ico", "image/vnd.microsoft.icon")
-		subfs, err := fs.Sub(StaticFs, "ui/dist")
+
+		uifs, err := fs.Sub(StaticFs, "ui/dist")
 		if err != nil {
 			panic(err)
 		}
-
-		sfs := spaFs{
-			root: http.FS(subfs),
-		}
-
-		server := gzipped.FileServer(sfs)
+		uihandler := gzipped.FileServer(
+			spaFs{
+				root: http.FS(uifs),
+			},
+		)
 
 		r.Route("/", func(r chi.Router) {
 			r.Use(CacheControl())
 			r.Use(IndexHTML())
-			r.Handle("/*", server)
+			if StaticDocsPath != "" {
+				docfs, err := fs.Sub(StaticDocsFs, StaticDocsPath)
+				if err != nil {
+					panic(err)
+				}
+				dochandler := gzipped.FileServer(http.FS(docfs))
+				r.HandleFunc("/docs/*", func(w http.ResponseWriter, r *http.Request) {
+					if ext := path.Ext(r.URL.Path); ext == "" {
+						r.URL.Path += ".html"
+					}
+					http.StripPrefix("/docs", dochandler).ServeHTTP(w, r)
+				})
+			}
+			r.Handle("/*", uihandler)
 		})
 		msg = fmt.Sprintf("ui at %v, %s", addr, msg)
 	}

ui/docs/.vitepress/.gitignore

@@ -0,0 +1 @@
+cache

ui/docs/.vitepress/config.mts

@@ -0,0 +1,63 @@
+import { defineConfig } from 'vitepress'
+
+// https://vitepress.dev/reference/site-config
+export default defineConfig({
+  title: "Photofield",
+  description: "Self-Hosted Personal Photo Gallery",
+  ignoreDeadLinks: [
+    /^https?:\/\/localhost/,
+  ],
+  base: '/docs/',
+  cleanUrls: true,
+  themeConfig: {
+    // https://vitepress.dev/reference/default-theme-config
+
+    logo: "/favicon-32x32.png",
+
+    editLink: {
+      pattern: 'https://github.com/smilyorg/photofield/edit/main/docs/:path'
+    },
+
+    nav: [
+      { text: 'Home', link: '/' },
+      { text: 'Quick Start', link: '/quick-start' },
+    ],
+
+    sidebar: [
+      {
+        text: 'Install',
+        items: [
+          { text: 'Quick Start', link: '/quick-start' },
+        ]
+      },
+      {
+        text: 'Usage',
+        link: '/usage',
+        items: [
+          { text: 'User Interface', link: '/user-interface' },
+          { text: 'Configuration', link: '/configuration' },
+          { text: 'Maintenance', link: '/maintenance' },
+        ]
+      },
+      {
+        text: 'Contributing',
+        link: '/contributing',
+        items: [
+          { text: 'Development', link: '/development' },
+        ]
+      },
+      {
+        text: 'About',
+        items: [
+          { text: 'License', link: '/license' },
+          { text: 'Credits', link: '/credits' },
+        ]
+      }
+    ],
+
+    socialLinks: [
+      { icon: 'github', link: 'https://github.com/SmilyOrg/photofield' }
+    ]
+
+  },
+})

ui/docs/.vitepress/theme/custom.css

@@ -0,0 +1,15 @@
+:root {
+  --vp-c-brand-1: #dd8888;
+  --vp-c-brand-2: #dd8888;
+  --vp-c-brand-3: #be6868;
+}
+
+.VPFeature article > img {
+  margin-left: -24px;
+  margin-top: -24px;
+  margin-bottom: 24px;
+  width: calc(100% + 48px);
+  max-width: calc(100% + 48px);
+  border-top-left-radius: 12px;
+  border-top-right-radius: 12px;
+}

ui/docs/.vitepress/theme/index.js

@@ -0,0 +1,5 @@
+// .vitepress/theme/index.js
+import DefaultTheme from 'vitepress/theme'
+import './custom.css'
+
+export default DefaultTheme