Skip to main content

Velox Help Developer Guide

This guide is for developers working on the Velox help repository. This repository contains user-facing documentation, Code Library content used by Velox, and a Docusaurus test site.

Repository Layout​

  • CodeLibrary\ - Markdown files used by the Velox app for the Help > Code Library menu.
  • CodeLibrary\_Index.json - generated Code Library index metadata.
  • CodeLibrary\Classes\, Constants\, Functions\, ScriptingGuide\, Types\, Variables\ - Code Library documentation areas.
  • CodeLibrary\Groups.docx and Groups.xlsx - supporting grouping/source documents.
  • CodeLibrary\_UPDATE INSTALL FOLDER.bat - copy script for Code Library content.
  • Velox\ - Docusaurus test site.
  • Velox\docs\ - Docusaurus documentation content.
  • Velox\src\ - Docusaurus pages/components/styles.
  • Velox\package.json - Node/Docusaurus dependencies and scripts.
  • 1. Velox Edit.bat - starts the Docusaurus dev server.
  • 2. Velox Build.bat - builds the Docusaurus site.
  • 3. Velox Test.bat - serves a built Docusaurus site.
  • velox-kb\VeloxPKB\docs\velox-kb\ - PKB/developer documentation for this repository.

Build Process​

Code Library​

The Code Library content is Markdown and JSON. There is no compile step for the Markdown itself.

The index file appears to be generated metadata. Do not manually edit CodeLibrary\_Index.json unless the task is specifically about generating or repairing that index.

Docusaurus Test Site​

The Docusaurus project lives in Velox\ and requires Node.js 18 or newer.

Common commands from Velox\:

npm install
npm run start
npm run build
npm run serve

The root batch files wrap those commands:

  • 1. Velox Edit.bat runs npm run start.
  • 2. Velox Build.bat runs npm run build.
  • 3. Velox Test.bat runs npm run serve.

The Docusaurus site still contains starter/template content. Confirm with the project owner before treating it as the active published help site.

Debugging​

For Code Library issues:

  • Check whether the Markdown file exists in the expected folder.
  • Check whether the item is represented in CodeLibrary\_Index.json.
  • Check whether the file was copied into the install repository or local ProgramData by a sync script.
  • Test from Velox Designer when the issue is about the Help > Code Library menu.

For Docusaurus issues:

  • Run npm run start from Velox\.
  • Fix broken links reported by Docusaurus.
  • Run npm run build before treating a site change as ready.
  • Use npm run serve to inspect the built output.

Coding Standards Inferred From The Project​

  • Write user-facing documentation, not internal developer notes.
  • Use clear Velox terminology: Velox, Velox Designer, VeloxService, VeloxAPIService, Flow, Action.
  • When behavior is unclear from code, say it is unclear rather than inventing behavior.
  • Keep documents organized in a hierarchy that helps a technical user find installation and usage guidance.
  • Do not rename or create Code Library files unless the task explicitly allows it.
  • Existing Code Library files may be edited, but preserve their role in the generated index.
  • Keep internal code-review findings and implementation details out of user docs unless users need them to operate Velox safely.
  • Do not add credentials, tokens, customer-specific data, or private operational details.

Typical Workflow​

For a user documentation update:

  1. Read the behavior from the owning code repository, usually velox, velox-data, velox-web, or velox-web2.
  2. Identify whether the change belongs in normal user docs, Code Library docs, or both.
  3. Edit Markdown in the appropriate area.
  4. Mark unclear behavior as unclear if code does not prove it.
  5. If Docusaurus is involved, run the local Docusaurus build.
  6. If Code Library content is involved, check the index/sync requirements.

For Code Library work:

  1. Locate the existing Markdown file.
  2. Preserve file names and folder structure unless explicitly asked to change them.
  3. Update content in a concise, reference-friendly style.
  4. Do not manually edit generated index metadata unless that is the task.
  5. Test the affected item in Velox Designer when possible.

Common Pitfalls​

  • CodeLibrary\_Index.json is large generated metadata; hand edits can break navigation.
  • The Docusaurus site currently contains starter content and may not be the production docs site.
  • Code Library files are consumed by the Velox application, not just by a static website.
  • Copy scripts use hard-coded paths and can update install or ProgramData folders.
  • User-facing docs should not include developer-only TODOs, speculative architecture notes, or private implementation details.
  • Documentation can drift from code because product behavior spans multiple repositories.

Important Concepts​

Code Library​

The Code Library is documentation surfaced inside Velox Designer. It contains scripting, class, function, type, variable, and constant references.

User Documentation​

User documentation explains how technical users install, configure, and operate Velox. It should be understandable without reading source code.

Docusaurus Site​

The Velox\ folder is a Docusaurus project used for website-style documentation experiments or publishing. Its production status is unclear from static review alone.

Install Sync​

Help content may be copied into the Install repository and local ProgramData folders for runtime use. Source changes should happen here first.

Unclear Areas​

  • The exact tool or command that generates CodeLibrary\_Index.json is unclear.
  • The production publishing path for the Docusaurus site is unclear.
  • Which help content is authoritative when Code Library and site docs overlap is unclear.