sc-ewon-flexy-common-docs

Repository for common documentation used in Ewon Flexy projects. This repository is intended to be used by projects implementing the sc-java-maven-starter-project repository template, or its functionalities, although it can be used by any project which may benefit from the common documentation provided.

Requirements

The following files must exist in the web-docs directory in the repository, and must match the linked templates/formats defined in the sc-java-maven-starter-project repository.

• ScDocusaurusConfig.js
• docusaurus.config.js
• package.json
• .gitignore

Note

While the ScDocusaurusConfig.js, docusaurus.config.js, .gitignore, and package.json files are required to exist and match the templates/formats provided by the sc-java-maven-starter-project repository, the values within these files must reflect the specific project's information and requirements.

Usage

The templates/formats provided by the sc-java-maven-starter-project repository already include basic configurations for the ScDocusaurusConfig.js, docusaurus.config.js, .gitignore, and package.json files.

The following sections specifically detail the relevant portions of the ScDocusaurusConfig.js, docusaurus.config.js, .gitignore, and package.json files which pertain to usage of the common documentation repository.

ScDocusaurusConfig.js

Example ScDocusaurusConfig object in the ScDocusaurusConfig.js file.

// CONFIGURATION ZONE - YOU CAN EDIT THESE LINES
const ScDocusaurusConfig = {
  ...
  commonDocRepoTargetBranchOrTag: 'vX.Y.Z',
  ...
};

The commonDocRepoTargetBranchOrTag value in the ScDocusaurusConfig object determines the specific branch or tag in the common documentation repository that is to be used. The value shall reflect the specific branch or tag in the common documentation repository that is to be used by the project.

Template/Format

The template/format for the ScDocusaurusConfig.js file can be found in the sc-java-maven-starter-project repository: ScDocusaurusConfig.js.

docusaurus.config.js

Example module.exports plugins section of docusaurus.config.js.

  // Plugins
  plugins: [
    [
      "docusaurus-plugin-remote-content",
      {
        // Imported documents
        name: "imported-docs",
        sourceBaseUrl: ScDocusaurusConfig.commonDocsRepoUrl + 'docs/',
        outDir: "docs/imported",
        noRuntimeDownloads: true,
        documents: [
          "setup/_configuration.mdx",
          "setup/_installation_or_upgrade.mdx",
          "sys_req/_sys_req_ewon_fw.mdx",
          "sys_req/_sys_req_java.mdx",
          "sys_req/_sys_req_maven.mdx",
        ],
      },
    ],
    [
      "docusaurus-plugin-remote-content",
      {
        // Imported images
        name: "imported-images",
        sourceBaseUrl: ScDocusaurusConfig.commonDocsRepoUrl + 'img',
        outDir: "static/img/imported",
        noRuntimeDownloads: true,
        documents: [
          "ewon/pages/ewon-tag-config-page-hist-logging.webp",
          "ewon/pages/ewon-web-page-home.webp",
          "ewon/setup/add-tag.gif",
          "ewon/setup/modify-tag.gif",
          "github/github-code-btn-download-zip.webp",
          "graphics/green-check-icon-cc0v1.webp",
          "graphics/documentation-icon-colorized-public-domain-192x.png",
          "graphics/home-icon-colorized-public-domain-192x.png",
          "graphics/quick-start-icon-colorized-public-domain-192x.png",
          "hms/hms-logo-rgb.webp",
          "hms/HMS-Logo-192x192.png",
          "hms/HMS-Logo-512x512.png",
          "hms/HMS-Logo-512x512.svg",
        ],
        requestConfig: { responseType: "arraybuffer" }
      }
    ],
    [
      "docusaurus-plugin-remote-content",
      {
        // Imported javascript
        name: "imported-js",
        sourceBaseUrl: ScDocusaurusConfig.commonDocsRepoUrl + 'js',
        outDir: "src/components/imported",
        noRuntimeDownloads: true,
        documents: [
          "highlight.js",
          "popover.js",
          "useGitHubReleaseInfo.js",
          "LatestVersionDisplay.js",
        ],
      }
    ]
  ],

Each plugin in the plugins section of the docusaurus.config.js file is responsible for downloading a specific type of content from the common documentation repository. The name of the plugin, the source base URL, the output directory, and the documents to download are specified in each plugin.

As required, the document values in each plugin shall be updated to reflect the specific documents, images, and/or javascript files that are to be downloaded from the common documentation repository.

Template/Format

The template/format for the docusaurus.config.js file can be found in the sc-java-maven-starter-project repository: docusaurus.config.js.

.gitignore

Example .gitignore file in the repository.

# Other GitIgnore rules
...

# Auto-downloaded common docs
docs/imported
static/img/imported
src/components/imported

Template/Format

The template/format for the .gitignore file can be found in the sc-java-maven-starter-project repository: .gitignore

package.json

Example scripts section of the package.json file.

{
  "scripts": {
    "other-scripts-1": "...",
    "start": "yarn fetch-remote-content && docusaurus start",
    "build": "yarn fetch-remote-content && docusaurus build",
    "other-scripts-2": "...",
    "clear": "yarn clear-remote-content && docusaurus clear",
    "other-scripts-3": "...",
    "fetch-remote-content": "docusaurus download-remote-imported-docs && docusaurus download-remote-imported-images && docusaurus download-remote-imported-js",
    "clear-remote-content": "docusaurus clear-remote-imported-docs && docusaurus clear-remote-imported-images && docusaurus clear-remote-imported-js",
    "other-scripts-4": "..."
  }
}

The fetch-remote-content and clear-remote-content scripts are responsible for downloading and clearing the imported content from the common documentation repository, respectively. The start, build, and clear scripts must be updated to invoke the fetch-remote-content and clear-remote-content scripts where necessary.

Template/Format

The template/format for the package.json file can be found in the sc-java-maven-starter-project repository: package.json