docgen-tool 2.1.2 → 3.0.0

package/.gitattributes

@@ -0,0 +1 @@
+* text=auto eol=lf

package/.github/workflows/deploy-website.yml

@@ -0,0 +1,28 @@
+name: Deploy Website
+on:
+  push:
+    branches: [ master ]
+permissions:
+  contents: write
+jobs:
+  build-and-deploy:
+    concurrency: ci-${{ github.ref }}
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout 🛎️
+        uses: actions/checkout@v3
+
+      - name: Install and Build 🔧
+        run: |
+          sudo apt-get install -y xfonts-base xfonts-75dpi
+          wget https://github.com/wkhtmltopdf/packaging/releases/download/0.12.6.1-2/wkhtmltox_0.12.6.1-2.jammy_amd64.deb
+          sudo dpkg -i wkhtmltox_0.12.6.1-2.jammy_amd64.deb
+          sudo apt-get -f install -y
+          wkhtmltopdf -V
+          yarn install --frozen-lockfile
+          yarn build:docs
+
+      - name: Deploy 🚀
+        uses: JamesIves/github-pages-deploy-action@v4
+        with:
+          folder: . # directory to deploy

package/.prettierignore

@@ -0,0 +1,4 @@
+docs/
+dist/
+source/require/webknife
+source/optional/katex

package/.prettierrc

@@ -0,0 +1,4 @@
+{
+  "singleQuote": true,
+  "trailingComma": "all"
+}

package/LICENSE

@@ -1,33 +1,35 @@
-DocGen is licensed under the MIT license
-----------------------------------------
-
-Copyright (c) 2015 Mark Macdonald
-
-DocGen includes third-party libraries (see below).
-
-MIT licensed:
--------------
-
-KaTeX: Copyright (c) 2014 Khan Academy, (https://github.com/Khan/KaTeX)
-
-Webknife: Copyright (c) 2015 The Webknife Project, (http://mtmacdonald.github.io/webknife)
-
-	Webknife includes third-party libraries attributed here: https://github.com/mtmacdonald/webknife/blob/master/LICENSE
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+DocGen is licensed under the MIT license
+----------------------------------------
+
+Copyright (c) Inkit Inc. and contributors
+
+Lead developer and contributor Mark Macdonald
+
+DocGen includes third-party libraries (see below).
+
+MIT licensed:
+-------------
+
+KaTeX: Copyright (c) 2014 Khan Academy, (https://github.com/Khan/KaTeX)
+
+Webknife: Copyright (c) 2015 The Webknife Project, (http://mtmacdonald.github.io/webknife)
+
+	Webknife includes third-party libraries attributed here: https://github.com/mtmacdonald/webknife/blob/master/LICENSE
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/{docgen → dist/docgen.js}

@@ -1,41 +1,32 @@
 #!/usr/bin/env node
-
-var docgen = require ('./source/docgen.js');
+var docgen = require('./source/docgen.js');
 var program = require('commander');
-var EOL = require('os').EOL;
-
 var generator = new docgen(process);
-
-function scaffold (command) {
+function scaffold(command) {
     generator.setOptions(command);
     generator.scaffold();
 }
-
-function run (command) {
+function run(command) {
     generator.setOptions(command);
     generator.run();
 }
-
 /*
     parse command-line arguments with node commander
         commander help: http://slides.com/timsanteford/conquering-commander-js
         command-line conventions: http://docopt.org
 */
-
+program.version(generator.getVersion()).usage('[command] [--option]');
 program
-    .version(generator.getVersion())
-    .usage('[command] [--option]');
-
-program.command('scaffold')
+    .command('scaffold')
     .usage('[--option]')
     .description('create a template input directory')
     .option('-o, --output [path]', 'path to the output directory (default: ./)', './')
     .option('-v, --verbose', 'show verbose output including detailed errors')
     .action(function (command) {
-        scaffold(command);
-    })
-
-program.command('run')
+    scaffold(command);
+});
+program
+    .command('run')
     .usage('[--option]')
     .description('create a static website from an input directory')
     .option('-i, --input [path]', 'path to the input directory [default: ./]', './')
@@ -51,11 +42,9 @@ program.command('run')
     .option('-R, --set-release-date [date]', 'override parameters.date (useful for build tools) [default: false]', false)
     .option('-w, --wkhtmltopdf-path [path]', 'specify a custom path to wkhtmltopdf [default: wkhtmltopdf]', 'wkhtmltopdf')
     .action(function (command) {
-        run(command);
-    });
-
+    run(command);
+});
 program.parse(process.argv);
-
 //if no arguments were provided, show help and then exit
 if (!process.argv.slice(2).length) {
     program.help();

package/docgen.js

@@ -0,0 +1,95 @@
+#!/usr/bin/env node
+
+let docgen = require('./source/docgen.js');
+let program = require('commander');
+
+let generator = new docgen(process);
+
+const scaffold = (command) => {
+  generator.setOptions(command);
+  generator.scaffold();
+};
+
+const run = (command) => {
+  generator.setOptions(command);
+  generator.run();
+};
+
+/*
+    parse command-line arguments with node commander
+        commander help: http://slides.com/timsanteford/conquering-commander-js
+        command-line conventions: http://docopt.org
+*/
+
+program.version(generator.getVersion()).usage('[command] [--option]');
+
+program
+  .command('scaffold')
+  .usage('[--option]')
+  .description('create a template input directory')
+  .option(
+    '-o, --output [path]',
+    'path to the output directory (default: ./)',
+    './',
+  )
+  .option('-v, --verbose', 'show verbose output including detailed errors')
+  .action((command) => {
+    scaffold(command);
+  });
+
+program
+  .command('run')
+  .usage('[--option]')
+  .description('create a static website from an input directory')
+  .option(
+    '-i, --input [path]',
+    'path to the input directory [default: ./]',
+    './',
+  )
+  .option(
+    '-o, --output [path]',
+    'path to the output directory [default: ./output]',
+    './output',
+  )
+  .option('-v, --verbose', 'show verbose output including detailed errors')
+  .option(
+    '-t, --page-toc',
+    'show a page table of contents at the top of each web page',
+  )
+  .option('-p, --pdf', 'create a PDF document')
+  .option(
+    '-d, --pdf-delay [milliseconds]',
+    'delay PDF printing to allow time for dynamic rendering [default: 2000]',
+    '2000',
+  )
+  .option('-m, --math-katex', 'enable KaTex mathematical expressions')
+  .option('-n, --math-mathjax', 'enable MathJax mathematical expressions')
+  .option(
+    '-r, --redirect',
+    'create an index.html in the parent directory that redirects to the homepage',
+  )
+  .option(
+    '-s, --set-version [version]',
+    'override parameters.version (useful for build tools) [default: false]',
+    false,
+  )
+  .option(
+    '-R, --set-release-date [date]',
+    'override parameters.date (useful for build tools) [default: false]',
+    false,
+  )
+  .option(
+    '-w, --wkhtmltopdf-path [path]',
+    'specify a custom path to wkhtmltopdf [default: wkhtmltopdf]',
+    'wkhtmltopdf',
+  )
+  .action((command) => {
+    run(command);
+  });
+
+program.parse(process.argv);
+
+//if no arguments were provided, show help and then exit
+if (!process.argv.slice(2).length) {
+  program.help();
+}

package/package.json

@@ -1,35 +1,62 @@
 {
   "name": "docgen-tool",
-  "version": "2.1.2",
+  "version": "3.0.0",
   "description": "A tool for creating HTML and PDF documentation",
-  "main": "docgen",
-  "bin" : { "docgen" : "./docgen" },
+  "main": "dist/docgen.js",
+  "bin": {
+    "docgen": "dist/docgen.js"
+  },
+  "scripts": {
+    "dev": "ts-node docgen.js run",
+    "build": "tsc -p tsconfig.json",
+    "run:build": "dist/docgen.js",
+    "build:docs": "ts-node docgen.js run -i ./source/user-guide -o ./docs -p -m -n -d 40000",
+    "test": "npm run prettier:check",
+    "test:run": "ts-node docgen.js run -i ./source/__test__/test-run -o ./source/__test__/test-run-output",
+    "prettier:check": "prettier --check 'docgen.js' '*.{js,json,css,less}'",
+    "prettier:fix": "prettier --write 'docgen.js' '*.{js,json,css,less}'"
+  },
+  "husky": {
+    "hooks": {
+      "pre-commit": "lint-staged"
+    }
+  },
+  "lint-staged": {
+    "*.{js,json,css,less}": "prettier --write",
+    "docgen": "prettier --write"
+  },
   "dependencies": {
-    "rsvp": "3.0.18",
-    "commander": "2.8.1",
-    "cheerio": "0.19.0",
-    "markdown-it": "4.2.1",
-    "moment" : "2.10.3",
-    "z-schema": "3.10.2",
-    "chalk": "1.0.0",
-    "spawn-args": "0.1.0",
-    "cli-spinner": "0.2.1",
-    "image-size": "0.3.5",
-    "fs-extra": "0.18.4"
+    "chalk": "^4.1.0",
+    "cheerio": "^1.0.0-rc.12",
+    "cli-spinner": "^0.2.10",
+    "commander": "^11.0.0",
+    "fs-extra": "^11.1.1",
+    "husky": "^4.3.0",
+    "image-size": "^1.0.2",
+    "lint-staged": "^10.5.1",
+    "markdown-it": "^13.0.1",
+    "moment": "^2.29.4",
+    "rsvp": "^4.8.5",
+    "spawn-args": "^0.2.0",
+    "z-schema": "^6.0.1"
   },
   "devDependencies": {
-    },
-  "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1"
+    "@types/node": "^20.3.1",
+    "eslint": "^8.43.0",
+    "eslint-config-prettier": "^8.8.0",
+    "prettier": "^2.1.2",
+    "ts-node": "^10.9.1",
+    "tslib": "^2.5.3",
+    "typescript": "^5.1.3"
   },
   "repository": {
     "type": "git",
     "url": "https://github.com/mtmacdonald/docgen"
   },
-  "author": "Mark Macdonald",
+  "author": "Inkit Inc. and contributors",
   "license": "MIT",
   "bugs": {
     "url": "https://github.com/mtmacdonald/docgen/issues"
   },
-  "homepage": "https://github.com/mtmacdonald/docgen"
-}
+  "homepage": "http://mtmacdonald.github.io/docgen/docs/index.html"
+}

package/source/__test__/test-run/contents.json

@@ -0,0 +1,12 @@
+[
+  {
+    "heading": "Test Run",
+    "column": 1,
+    "pages": [
+      {
+        "title": "Overview",
+        "source": "overview.txt"
+      }
+    ]
+  }
+]

package/source/__test__/test-run/overview.txt

@@ -0,0 +1,3 @@
+# DocGen Test Case
+
+An example documentation site for testing.

package/source/__test__/test-run/parameters.json

@@ -0,0 +1,32 @@
+{
+  "title": "DocGen test case",
+  "name": "DocGen test case",
+  "version": "1.0.0",
+  "date": "27/06/2023",
+  "organization": {
+    "name": "DocGen Test Case",
+    "url": "https://www.inkit.com"
+  },
+  "author": {
+    "name": "DocGen Test Case",
+    "url": "https://www.inkit.com"
+  },
+  "owner": {
+    "name": "DocGen Test Case",
+    "url": "https://www.inkit.com"
+  },
+  "contributors": [],
+  "website": {
+    "name": "Github",
+    "url": "https://github.com/mtmacdonald/docgen"
+  },
+  "backlink": {
+    "name": "",
+    "url": ""
+  },
+  "module": "",
+  "id": "",
+  "summary": "DocGen test case.",
+  "marking": "MIT License.",
+  "legalese": ""
+}

package/source/__test__/test-run/release-notes.txt

@@ -0,0 +1,4 @@
+DocGen Test Case 1.0.0 released 27/06/2023
+------------------------------------------
+
+- Initial version of test case