Moved documentation to Writerside and created GitHub Pages build proc…

…ess.
aidc-toolkit · Sep 28, 2024 · 58ca233 · 58ca233
1 parent 915191b
commit 58ca233
Show file tree

Hide file tree

Showing 107 changed files with 904 additions and 3,706 deletions.
diff --git a/.github/workflows/build-pages.yml b/.github/workflows/build-pages.yml
@@ -0,0 +1,147 @@
+name: Build GitHub Pages
+
+on:
+  push:
+    branches: ["main"]
+  workflow_dispatch:
+
+permissions:
+  id-token: write
+  pages: write
+
+env:
+  NODE_VERSION: 22
+  INSTANCE: "Writerside/doc"
+  ARTIFACT: "webHelpDOC2-all.zip"
+  DOCKER_VERSION: "242.21870"
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+#      # Insert this at the appropriate step to start a terminal session for debugging.
+#      - name: Setup tmate session
+#        uses: mxschmitt/action-tmate@v3
+
+      - name: Setup node
+        uses: actions/setup-node@v4
+        with:
+          node-version: ${{ env.NODE_VERSION }}
+          registry-url: https://registry.npmjs.org/
+
+      - name: Checkout default repository (doc)
+        uses: actions/checkout@v4
+
+      - name: Build Writerside artifact
+        uses: JetBrains/writerside-github-action@v4
+        with:
+          instance: ${{ env.INSTANCE }}
+          artifact: ${{ env.ARTIFACT }}
+          docker-version: ${{ env.DOCKER_VERSION }}
+
+      - name: Create build directory
+        run: mkdir build
+
+      - name: Unzip artifact to pages
+        run: unzip -O UTF-8 -qq artifacts/${{ env.ARTIFACT }} -d build/pages
+
+      # Builds include "npm install @rollup/rollup-linux-x64-gnu", which is necessary to work around platform-specific
+      # optional dependencies bug (https://github.com/npm/cli/issues/4828).
+
+      - name: Checkout dev
+        uses: actions/checkout@v4
+        with:
+          repository: aidc-toolkit/dev
+          path: build/dev
+
+      - name: Build dev
+        working-directory: "build/dev"
+        run: |
+          npm link
+          npm ci
+          npm install @rollup/rollup-linux-x64-gnu
+          npm run build
+
+      - name: Checkout core
+        uses: actions/checkout@v4
+        with:
+          repository: aidc-toolkit/core
+          path: build/core
+
+      - name: Build core
+        working-directory: "build/core"
+        run: |
+          npm link
+          npm link @aidc-toolkit/dev
+          npm ci
+          npm install @rollup/rollup-linux-x64-gnu
+          npm run build-dev
+
+      - name: Checkout utility
+        uses: actions/checkout@v4
+        with:
+          repository: aidc-toolkit/utility
+          path: build/utility
+
+      - name: Build utility
+        working-directory: "build/utility"
+        run: |
+          npm link
+          npm link @aidc-toolkit/dev @aidc-toolkit/core
+          npm ci
+          npm install @rollup/rollup-linux-x64-gnu
+          npm run build-dev
+
+      - name: Checkout gs1
+        uses: actions/checkout@v4
+        with:
+          repository: aidc-toolkit/gs1
+          path: build/gs1
+
+      - name: Build gs1
+        working-directory: "build/gs1"
+        run: |
+          npm link
+          npm link @aidc-toolkit/dev @aidc-toolkit/core @aidc-toolkit/utility
+          npm ci
+          npm install @rollup/rollup-linux-x64-gnu
+          npm run build-dev
+
+      - name: Checkout demo
+        uses: actions/checkout@v4
+        with:
+          repository: aidc-toolkit/demo
+          path: build/demo
+
+      - name: Build demo
+        working-directory: "build/demo"
+        run: |
+          npm link @aidc-toolkit/dev @aidc-toolkit/core @aidc-toolkit/utility @aidc-toolkit/gs1
+          npm ci
+          npm install @rollup/rollup-linux-x64-gnu
+          npm run build -- --outDir ../pages/demo
+
+      - name: Checkout doc
+        uses: actions/checkout@v4
+        with:
+          path: build/doc
+
+      - name: Generate API documentation
+        working-directory: "build/doc"
+        run: |
+          npm link @aidc-toolkit/dev
+          npm ci
+          npm install @rollup/rollup-linux-x64-gnu
+          npm run typedoc -- --out ../pages/api
+
+      - name: Configure GitHub Pages
+        uses: actions/configure-pages@v4
+
+      - name: Package and upload pages directory
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: build/pages
+
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4
diff --git a/.gitignore b/.gitignore
@@ -1,2 +1 @@
 /node_modules/
-/Writerside/
diff --git a/.idea/codeStyles/codeStyleConfig.xml b/.idea/codeStyles/codeStyleConfig.xml
diff --git a/.idea/inspectionProfiles/Project_Default.xml b/.idea/inspectionProfiles/Project_Default.xml
diff --git a/Writerside/c.list b/Writerside/c.list
@@ -0,0 +1,6 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE categories
+        SYSTEM "https://resources.jetbrains.com/writerside/1.0/categories.dtd">
+<categories>
+    <category id="wrs" name="Writerside documentation" order="1"/>
+</categories>
diff --git a/Writerside/cfg/buildprofiles.xml b/Writerside/cfg/buildprofiles.xml
@@ -0,0 +1,17 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE buildprofiles SYSTEM "https://resources.jetbrains.com/writerside/1.0/build-profiles.dtd">
+<buildprofiles xsi:noNamespaceSchemaLocation="https://resources.jetbrains.com/writerside/1.0/build-profiles.xsd"
+               xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
+
+    <build-profile instance="doc">
+        <variables>
+            <noindex-content>false</noindex-content>
+            <custom-favicons>icon-144.png</custom-favicons>
+            <header-logo>icon-144.png</header-logo>
+            <download-title>Join us on GitHub</download-title>
+            <download-page>https://github.com/aidc-toolkit</download-page>
+            <showDownloadButton>true</showDownloadButton>
+        </variables>
+    </build-profile>
+
+</buildprofiles>
diff --git a/Writerside/doc.tree b/Writerside/doc.tree
@@ -0,0 +1,13 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE instance-profile
+        SYSTEM "https://resources.jetbrains.com/writerside/1.0/product-profile.dtd">
+
+<instance-profile id="doc"
+                 name="AIDC Toolkit"
+                 start-page="Overview.topic">
+
+    <toc-element topic="Overview.topic"/>
+    <toc-element topic="Core-Package.topic"/>
+    <toc-element topic="Utility-Package.topic"/>
+    <toc-element topic="GS1-Package.topic"/>
+</instance-profile>
diff --git a/resource/icon-144.png → Writerside/images/icon-144.png b/resource/icon-144.png → Writerside/images/icon-144.png
diff --git a/Writerside/redirection-rules.xml b/Writerside/redirection-rules.xml
@@ -0,0 +1,9 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE rules SYSTEM "https://resources.jetbrains.com/writerside/1.0/redirection-rules.dtd">
+<rules>
+    <!-- format is as follows
+    <rule id="<unique id>">
+        <accepts>page.html</accepts>
+    </rule>
+    -->
+</rules>
diff --git a/Writerside/topics/Core-Package.topic b/Writerside/topics/Core-Package.topic
@@ -0,0 +1,138 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE topic
+        SYSTEM "https://resources.jetbrains.com/writerside/1.0/xhtml-entities.dtd">
+<topic xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+       xsi:noNamespaceSchemaLocation="https://resources.jetbrains.com/writerside/1.0/topic.v2.xsd"
+       title="Core Package" id="Core-Package">
+    <p>
+        The <code>core</code> package provides support for internationalization, built on the robust and popular
+        <a href="https://i18next.com">i18next</a> package. Applications can take advantage of the additional abstraction
+        provided by the <code>core</code> package by
+        <a href="%apiBase%/functions/Core.i18nAddResourceBundle.html">adding their own resource bundles</a> or can
+        manage internationalization themselves.
+    </p>
+
+    <chapter title="Internationalization" id="internationalization">
+        <p>
+            Applications built on the AIDC Toolkit <format style="bold">must</format> initialize internationalization
+            first via this package. Support is available for the following environments:
+        </p>
+
+        <list>
+            <li>
+                <a href="#command-line-interface">Command-line interface</a>
+                <list>
+                    <li>Unit tests</li>
+                    <li>Batch applications</li>
+                </list>
+            </li>
+            <li>
+                Web server
+                <warning>
+                    Not yet implemented.
+                </warning>
+            </li>
+            <li>
+                <a href="#web-browser">Web browser</a>
+            </li>
+        </list>
+
+        <chapter title="Command-line interface" id="command-line-interface">
+            <p>
+                Initializing internationalization for a command-line interface application is straightforward:
+            </p>
+
+            <code-block lang="typescript" noinject="true">
+                await i18nInit(I18NEnvironment.CLI);
+            </code-block>
+        </chapter>
+
+        <chapter title="Web browser" id="web-browser">
+            <p>
+                Initializing internationalization for a web browser requires awaiting the fulfillment of the
+                <code>Promise</code> returned by the call to <code>i18nInit()</code> before rendering any content. For
+                example, in the React framework, this may be accomplished as follows:
+            </p>
+
+            <procedure id="web-browser-internationalization">
+                <step>
+                    <p>
+                        Define an application state variable.
+                    </p>
+
+                    <code-block lang="typescript" noinject="true">
+                        interface AppState {
+                            i18nInitialized: boolean;
+                            // Define additional state variables here.
+                        }
+                    </code-block>
+                </step>
+
+                <step>
+                    <p>
+                        Define the application class and initialize the state.
+                    </p>
+
+                    <code-block lang="typescript" noinject="true">
+                        export default class App extends AppComponent&lt;object, AppState&gt; {
+                            override state: AppState = {
+                                i18nInitialized: false,
+                                // Initialize additional state variables here.
+                            };
+
+                            // Remainder of class.
+                        }
+                    </code-block>
+                </step>
+
+                <step>
+                    <p>
+                        Override the <code>componentDidMount()</code> method to initialize internationalization and to
+                        force refresh once the <code>Promise</code> is fulfilled.
+                    </p>
+
+                    <code-block lang="typescript" noinject="true">
+                        override componentDidMount(): void {
+                            i18nInit(I18NEnvironment.Browser, true).then((initialized) => {
+                                if (initialized) {
+                                    // Force refresh.
+                                    this.setState(state => ({
+                                        ...state,
+                                        i18nInitialized: initialized
+                                    }));
+                                }
+                            }).catch((e: unknown) => {
+                                console.error(e);
+                                alert(e);
+                            });
+                        }
+                    </code-block>
+                </step>
+
+                <step>
+                    <p>
+                        Override the <code>render()</code> method to render the initial content, but only once the
+                        application has been initialized.
+                    </p>
+
+                    <code-block lang="typescript" noinject="true">
+                        override render(): ReactElement {
+                            return this.state.i18nInitialized ?
+                                // Render the application.
+                                &lt;Navbar className="d-flex" expand="lg"&gt;
+                                    // ...
+                                &lt;/Navbar&gt; :
+                                    // Render nothing.
+                                &lt;&gt;&lt;/&gt;;
+                        }
+                    </code-block>
+                </step>
+            </procedure>
+
+            <tip>
+                For a complete example, including how to use application-specific resource bundles, see the
+                <a href="%gitHubBase%/demo">AIDC Toolkit demo source</a>.
+            </tip>
+        </chapter>
+    </chapter>
+</topic>
diff --git a/Writerside/topics/GS1-Package.topic b/Writerside/topics/GS1-Package.topic
@@ -0,0 +1,23 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE topic
+        SYSTEM "https://resources.jetbrains.com/writerside/1.0/xhtml-entities.dtd">
+<topic xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+       xsi:noNamespaceSchemaLocation="https://resources.jetbrains.com/writerside/1.0/topic.v2.xsd"
+       title="GS1 Package" id="GS1-Package">
+    <chapter title="Check digits and check character pairs" id="check-digits-and-check-character-pairs">
+        <chapter title="Check digit - GS1 identification key" id="check-digit-gs1-identification-key">
+        </chapter>
+        <chapter title="Check digit - price/weight encoding" id="check-digit-price-weight-encoding">
+        </chapter>
+        <chapter title="Check character pair - GS1 identification key" id="check-character-pair-gs1-identification-key">
+        </chapter>
+    </chapter>
+    <chapter title="GS1 identification keys" id="gs1-identification-keys">
+        <chapter title="Prefix types" id="prefix=types">
+        </chapter>
+        <chapter title="GS1 identification key validation" id="gs1-identification-key-validation">
+        </chapter>
+        <chapter title="GS1 identification key creation" id="gs1-identification-key-creation">
+        </chapter>
+    </chapter>
+</topic>