Add docs and workflow for dep

Also rename dep to publishing for consistency with existing names

.github/workflows/publishing.yml

@@ -0,0 +1,102 @@
+name: logseq/publishing CI
+
+on:
+  # Path filters ensure jobs only kick off if a change is made to publishing or
+  # its local dependencies
+  push:
+    branches: [master]
+    paths:
+      - 'deps/publishing/**'
+      # db is a local dep that could break functionality in this lib and should trigger this
+      - 'deps/db/**'
+      - '.github/workflows/publishing.yml'
+      - '!deps/publishing/**.md'
+  pull_request:
+    branches: [master]
+    paths:
+      - 'deps/publishing/**'
+      - 'deps/db/**'
+      - '.github/workflows/publishing.yml'
+      - '!deps/publishing/**.md'
+
+defaults:
+  run:
+    working-directory: deps/publishing
+
+env:
+  CLOJURE_VERSION: '1.10.1.763'
+  # This is the same as 1.8.
+  JAVA_VERSION: '11'
+  # This is the latest node version we can run.
+  NODE_VERSION: '18'
+  BABASHKA_VERSION: '1.0.168'
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v3
+
+      - name: Set up Node
+        uses: actions/setup-node@v3
+        with:
+          node-version: ${{ env.NODE_VERSION }}
+          cache: 'yarn'
+          cache-dependency-path: deps/publishing/yarn.lock
+
+      - name: Set up Java
+        uses: actions/setup-java@v3
+        with:
+          distribution: 'zulu'
+          java-version: ${{ env.JAVA_VERSION }}
+
+      - name: Set up Babashka
+        uses: DeLaGuardo/[email protected]
+        with:
+          bb: ${{ env.BABASHKA_VERSION }}
+
+      - name: Fetch yarn deps
+        run: yarn install --frozen-lockfile
+
+      - name: Run nbb-logseq tests
+        run: yarn test
+
+      # In this job because it depends on an npm package
+      - name: Load namespaces into nbb-logseq
+        run: bb test:load-all-namespaces-with-nbb .
+
+  lint:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v3
+
+      - name: Set up Java
+        uses: actions/setup-java@v3
+        with:
+          distribution: 'zulu'
+          java-version: ${{ env.JAVA_VERSION }}
+
+      - name: Set up Clojure
+        uses: DeLaGuardo/[email protected]
+        with:
+          cli: ${{ env.CLOJURE_VERSION }}
+          bb: ${{ env.BABASHKA_VERSION }}
+
+      - name: Run clj-kondo lint
+        run: clojure -M:clj-kondo --lint src test
+
+      - name: Carve lint for unused vars
+        run: bb lint:carve
+
+      - name: Lint for vars that are too large
+        run: bb lint:large-vars
+
+      - name: Lint for namespaces that aren't documented
+        run: bb lint:ns-docstrings
+
+      - name: Lint for public vars that are private based on usage
+        run: bb lint:minimize-public-vars

bb.edn

@@ -34,9 +34,9 @@
   dev:build-publishing
   logseq.tasks.dev/build-publishing
 
-  dev:publish-spa
+  dev:publishing
   {:depends [dev:build-publishing]
-   :doc "Build publish spa app given graph and output dirs"
+   :doc "Build publishing spa app given graph and output dirs"
    :task (apply shell {:dir "scripts"}
            "yarn -s nbb-logseq -cp src -m logseq.tasks.dev.publishing"
            (into ["static"] *command-line-args*))}

deps.edn

@@ -29,7 +29,7 @@
   org.clojars.mmb90/cljs-cache          {:mvn/version "0.1.4"}
   logseq/common                         {:local/root "deps/common"}
   logseq/graph-parser                   {:local/root "deps/graph-parser"}
-  logseq/publish-spa                    {:local/root "deps/publish-spa"}
+  logseq/publishing                     {:local/root "deps/publishing"}
   metosin/malli                         {:mvn/version "0.10.0"}
   fipp/fipp                             {:mvn/version "0.6.26"}}
 

deps/db/README.md

@@ -13,7 +13,7 @@ two main namespaces, `logseq.db` and `logseq.db.rules`.
 
 ## Usage
 
-See usage in `deps/graph-parser` and in the Logseq app.
+See the frontend for example usage.
 
 ## Dev
 

deps/graph-parser/README.md

@@ -18,7 +18,9 @@ CLIs.
 
 ## Usage
 
-See `logseq.graph-parser.cli-test` for now. A real world example is coming soon.
+See `logseq.graph-parser.cli-test` and [nbb-logseq example
+scripts](https://github.com/logseq/nbb-logseq/tree/main/examples) for example
+usage.
 
 ## Dev
 
@@ -34,11 +36,11 @@ To run linters and tests, you'll want to install yarn dependencies once:
 yarn install
 ```
 
-This step is not needed if you're just running the application.
+This step is not needed if you're just running the frontend application.
 
 ### Testing
 
-Since this file is compatible with cljs and nbb-logseq, tests are run against both languages.
+Since this library is compatible with cljs and nbb-logseq, tests are run against both languages.
 
 ClojureScript tests use https://github.com/Olical/cljs-test-runner. To run tests:
 ```

deps/publishing/.carve/config.edn

@@ -0,0 +1,4 @@
+{:paths ["src"]
+ :api-namespaces [;; for nbb-logseq CLIs
+                  logseq.publishing]
+ :report {:format :ignore}}

deps/publish-spa/.clj-kondo/config.edn → deps/publishing/.clj-kondo/config.edn

@@ -7,7 +7,7 @@
   {:aliases {clojure.string string}}}
 
  :lint-as
- {logseq.publish-spa.test.helper/deftest-async clojure.test/deftest
+ {logseq.publishing.test.helper/deftest-async clojure.test/deftest
   promesa.core/let clojure.core/let}
  :skip-comments true
  :output {:progress true}}

deps/publishing/README.md

@@ -0,0 +1,52 @@
+## Description
+
+This library handles exporting the `frontend.publishing` single page
+application. This library is compatible with ClojureScript and with
+node/[nbb-logseq](https://github.com/logseq/nbb-logseq) to respectively provide
+frontend and Electron/commandline functionality.
+
+## API
+
+This library is under the parent namespace `logseq.publishing`. This library
+provides two namespaces for node/CLI contexts, `logseq.publishing` and
+`logseq.publishing.export` and two namespaces for the frontend,
+`logseq.publishing.html` and `logseq.publishing.db`.
+
+## Usage
+
+See `logseq.tasks.dev.publishing` for a CLI example. See the frontend for cljs usage.
+
+## Dev
+
+This follows the practices that [the Logseq frontend
+follows](/docs/dev-practices.md). Most of the same linters are used, with
+configurations that are specific to this library. See [this library's CI
+file](/.github/workflows/publishing.yml) for linting examples.
+
+### Setup
+
+To run linters and tests, you'll want to install yarn dependencies once:
+```
+yarn install
+```
+
+This step is not needed if you're just running the frontend application.
+
+### Testing
+
+Testing is done with nbb-logseq and
+[nbb-test-runner](https://github.com/nextjournal/nbb-test-runner). Some basic
+usage:
+
+```
+# Run all tests
+$ yarn test
+# List available options
+$ yarn test -H
+# Run tests with :focus metadata flag
+$ yarn test -i focus
+```
+
+### Managing dependencies
+
+See [standard nbb/cljs library advice in graph-parser](/deps/graph-parser/README.md#managing-dependencies).

deps/publishing/bb.edn

@@ -0,0 +1,30 @@
+{:min-bb-version "1.0.168"
+ :deps
+ {logseq/bb-tasks
+  #_{:local/root "../../../bb-tasks"}
+  {:git/url "https://github.com/logseq/bb-tasks"
+   :git/sha "0d49051909bfa0c6b414e86606d82b4ea54f382c"}}
+
+ :pods
+ {clj-kondo/clj-kondo {:version "2023.03.17"}}
+
+ :tasks
+ {test:load-all-namespaces-with-nbb
+  logseq.bb-tasks.nbb.test/load-all-namespaces
+
+  lint:large-vars
+  logseq.bb-tasks.lint.large-vars/-main
+
+  lint:carve
+  logseq.bb-tasks.lint.carve/-main
+
+  lint:ns-docstrings
+  logseq.bb-tasks.lint.ns-docstrings/-main
+
+  lint:minimize-public-vars
+  logseq.bb-tasks.lint.minimize-public-vars/-main}
+
+ :tasks/config
+ {:large-vars
+  ;; For vars with long running html
+  {:metadata-exceptions #{:large-vars/html}}}}

deps/publishing/deps.edn

@@ -0,0 +1,7 @@
+{:paths ["src"]
+ :deps
+ {logseq/db {:local/root "../db"}}
+
+ :aliases
+ {:clj-kondo {:replace-deps {clj-kondo/clj-kondo {:mvn/version "2023.03.17"}}
+              :main-opts    ["-m" "clj-kondo.main"]}}}

deps/publish-spa/package.json → deps/publishing/package.json

@@ -1,5 +1,5 @@
 {
-  "name": "@logseq/publish-spa",
+  "name": "@logseq/publishing",
   "version": "1.0.0",
   "private": true,
   "devDependencies": {

deps/publish-spa/src/logseq/publish_spa.cljs → deps/publishing/src/logseq/publishing.cljs

@@ -1,7 +1,7 @@
-(ns logseq.publish-spa
+(ns logseq.publishing
   "This node only ns provides api fns for exporting a publishing app"
-  (:require [logseq.publish-spa.html :as publish-html]
-            [logseq.publish-spa.export :as publish-export]))
+  (:require [logseq.publishing.html :as publish-html]
+            [logseq.publishing.export :as publish-export]))
 
 (defn export
   "Exports the given graph-dir and db to the specific output-dir. Most of the graph

deps/publish-spa/src/logseq/publish_spa/db.cljs → deps/publishing/src/logseq/publishing/db.cljs

@@ -1,9 +1,10 @@
-(ns logseq.publish-spa.db
+(ns logseq.publishing.db
+  "Provides db fns and associated util fns for publishing"
   (:require [datascript.core :as d]
             [logseq.db.schema :as db-schema]
             [clojure.string :as string]))
 
-(defn get-area-block-asset-url
+(defn ^:api get-area-block-asset-url
   "Returns asset url for an area block used by pdf assets. This lives in this ns
   because it is used by this dep and needs to be indepent from the frontend app"
   [block page]

deps/publish-spa/src/logseq/publish_spa/export.cljs → deps/publishing/src/logseq/publishing/export.cljs

@@ -1,16 +1,16 @@
-(ns logseq.publish-spa.export
+(ns logseq.publishing.export
   "This electron only ns (for the main process) exports files from multiple
   locations to provide a complete publishing app"
   (:require ["fs-extra" :as fse]
             ["path" :as node-path]
             ["fs" :as fs]
             [promesa.core :as p]))
 
-(def js-files
+(def ^:api js-files
   "js files from publishing release build"
   ["main.js" "code-editor.js" "excalidraw.js" "tldraw.js"])
 
-(def static-dirs
+(def ^:api static-dirs
   "dirs under static dir to copy over"
   ["css" "fonts" "icons" "img" "js"])
 

deps/publish-spa/src/logseq/publish_spa/html.cljs → deps/publishing/src/logseq/publishing/html.cljs

@@ -1,11 +1,11 @@
-(ns logseq.publish-spa.html
+(ns logseq.publishing.html
   "This frontend only ns builds the publishing html including doing all the
 necessary db filtering"
   (:require [clojure.string :as string]
             [goog.string :as gstring]
             [goog.string.format]
             [datascript.transit :as dt]
-            [logseq.publish-spa.db :as db]))
+            [logseq.publishing.db :as db]))
 
 ;; Copied from hiccup but tweaked for publish usage
 ;; Any changes here should also be made in frontend.publishing/unescape-html
@@ -20,7 +20,7 @@ necessary db filtering"
       (string/replace "'" "logseq____'")))
 
 ;; Copied from https://github.com/babashka/babashka/blob/8c1077af00c818ade9e646dfe1297bbe24b17f4d/examples/notes.clj#L21
-(defn html [v]
+(defn- html [v]
   (cond (vector? v)
     (let [tag (first v)
           attrs (second v)
@@ -39,7 +39,7 @@ necessary db filtering"
     (string/join " " (map html v))
     :else (str v)))
 
-(defn publishing-html
+(defn- ^:large-vars/html publishing-html
   [transit-db app-state options]
   (let [{:keys [icon name alias title description url]} options
         icon (or icon "static/img/logo.png")

deps/publish-spa/test/logseq/publish_spa/db_test.cljs → deps/publishing/test/logseq/publishing/db_test.cljs

@@ -1,7 +1,7 @@
-(ns logseq.publish-spa.db-test
+(ns logseq.publishing.db-test
   (:require [cljs.test :refer [deftest is]]
             [clojure.set :as set]
-            [logseq.publish-spa.db :as publish-db]
+            [logseq.publishing.db :as publish-db]
             [logseq.graph-parser :as graph-parser]
             [datascript.core :as d]
             [logseq.db :as ldb]))

deps/publish-spa/test/logseq/publish_spa/export_test.cljs → deps/publishing/test/logseq/publishing/export_test.cljs

@@ -1,7 +1,7 @@
-(ns logseq.publish-spa.export-test
+(ns logseq.publishing.export-test
   (:require [cljs.test :as t :refer [is use-fixtures async]]
-            [logseq.publish-spa.test.helper :as test-helper :include-macros true :refer [deftest-async]]
-            [logseq.publish-spa.export :as publish-export]
+            [logseq.publishing.test.helper :as test-helper :include-macros true :refer [deftest-async]]
+            [logseq.publishing.export :as publish-export]
             [promesa.core :as p]
             [clojure.set :as set]
             ["fs" :as fs]

deps/publish-spa/test/logseq/publish_spa/test/helper.clj → deps/publishing/test/logseq/publishing/test/helper.clj

@@ -1,4 +1,4 @@
-(ns logseq.publish-spa.test.helper)
+(ns logseq.publishing.test.helper)
 
 ;; Copied from https://github.com/babashka/nbb/blob/e5d84b0fac59774f5d7a4a9e807240cce04bf252/test/nbb/test_macros.clj
 (defmacro deftest-async