Initial structure of docbook tool process

.github/workflows/phpcs.yml

@@ -0,0 +1,46 @@
+name: "Coding Standards"
+
+on:
+  pull_request:
+  push:
+
+jobs:
+  coding-standards:
+    name: "Coding Standards"
+
+    runs-on: ${{ matrix.operating-system }}
+
+    strategy:
+      matrix:
+        php-version:
+          - "8.0"
+        operating-system:
+          - "ubuntu-latest"
+
+    steps:
+      - name: "Checkout"
+        uses: "actions/checkout@v2"
+
+      - name: "Install wkhtmltopdf"
+        run: "sudo apt-get install xvfb libfontconfig wkhtmltopdf"
+
+      - name: "Install PHP"
+        uses: "shivammathur/setup-php@v2"
+        with:
+          coverage: "none"
+          php-version: "${{ matrix.php-version }}"
+
+      - name: "Cache dependencies"
+        uses: "actions/cache@v2"
+        with:
+          path: |
+            ~/.composer/cache
+            vendor
+          key: "php-${{ matrix.php-version }}-${{ matrix.dependencies }}"
+          restore-keys: "php-${{ matrix.php-version }}-${{ matrix.dependencies }}"
+
+      - name: "Install locked dependencies"
+        run: "composer install --no-interaction --no-progress --no-suggest"
+
+      - name: "Run phpcs"
+        run: "vendor/bin/phpcs"

.github/workflows/phpunit.yml

@@ -0,0 +1,59 @@
+name: "PHPUnit tests"
+
+on:
+  pull_request:
+  push:
+
+jobs:
+  tests:
+    name: "PHPUnit tests"
+
+    runs-on: ${{ matrix.operating-system }}
+
+    strategy:
+      matrix:
+        dependencies:
+          - "lowest"
+          - "highest"
+          - "locked"
+        php-version:
+          - "8.0"
+        operating-system:
+          - "ubuntu-latest"
+
+    steps:
+      - name: "Checkout"
+        uses: "actions/checkout@v2"
+
+      - name: "Install wkhtmltopdf"
+        run: "sudo apt-get install xvfb libfontconfig wkhtmltopdf"
+
+      - name: "Install PHP"
+        uses: "shivammathur/setup-php@v2"
+        with:
+          coverage: "none"
+          php-version: "${{ matrix.php-version }}"
+
+      - name: "Cache dependencies"
+        uses: "actions/cache@v2"
+        with:
+          path: |
+            ~/.composer/cache
+            vendor
+          key: "php-${{ matrix.php-version }}-${{ matrix.dependencies }}"
+          restore-keys: "php-${{ matrix.php-version }}-${{ matrix.dependencies }}"
+
+      - name: "Install lowest dependencies"
+        if: ${{ matrix.dependencies == 'lowest' }}
+        run: "composer update --prefer-lowest --no-interaction --no-progress --no-suggest"
+
+      - name: "Install highest dependencies"
+        if: ${{ matrix.dependencies == 'highest' }}
+        run: "composer update --no-interaction --no-progress --no-suggest"
+
+      - name: "Install locked dependencies"
+        if: ${{ matrix.dependencies == 'locked' }}
+        run: "composer install --no-interaction --no-progress --no-suggest"
+
+      - name: "Run phpunit"
+        run: "xvfb-run -- vendor/bin/phpunit"

.github/workflows/psalm.yml

@@ -0,0 +1,46 @@
+name: "Static Analysis"
+
+on:
+  pull_request:
+  push:
+
+jobs:
+  static-analysis:
+    name: "Static Analysis"
+
+    runs-on: ${{ matrix.operating-system }}
+
+    strategy:
+      matrix:
+        php-version:
+          - "8.0"
+        operating-system:
+          - "ubuntu-latest"
+
+    steps:
+      - name: "Checkout"
+        uses: "actions/checkout@v2"
+
+      - name: "Install wkhtmltopdf"
+        run: "sudo apt-get install xvfb libfontconfig wkhtmltopdf"
+
+      - name: "Install PHP"
+        uses: "shivammathur/setup-php@v2"
+        with:
+          coverage: "none"
+          php-version: "${{ matrix.php-version }}"
+
+      - name: "Cache dependencies"
+        uses: "actions/cache@v2"
+        with:
+          path: |
+            ~/.composer/cache
+            vendor
+          key: "php-${{ matrix.php-version }}-${{ matrix.dependencies }}"
+          restore-keys: "php-${{ matrix.php-version }}-${{ matrix.dependencies }}"
+
+      - name: "Install locked dependencies"
+        run: "composer install --no-interaction --no-progress --no-suggest"
+
+      - name: "Run psalm"
+        run: "vendor/bin/psalm"

.github/workflows/release-on-milestone-closed-triggering-release-event.yml

@@ -0,0 +1,61 @@
+# Alternate workflow example.
+# This one is identical to the one in release-on-milestone.yml, with one change:
+# the Release step uses the ORGANIZATION_ADMIN_TOKEN instead, to allow it to
+# trigger a release workflow event. This is useful if you have other actions
+# that intercept that event.
+
+name: "Automatic Releases"
+
+on:
+  milestone:
+    types:
+      - "closed"
+
+jobs:
+  release:
+    name: "GIT tag, release & create merge-up PR"
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: "Checkout"
+        uses: "actions/checkout@v2"
+
+      - name: "Release"
+        uses: "laminas/automatic-releases@v1"
+        with:
+          command-name: "laminas:automatic-releases:release"
+        env:
+          "GITHUB_TOKEN": ${{ secrets.ORGANIZATION_ADMIN_TOKEN }}
+          "SIGNING_SECRET_KEY": ${{ secrets.SIGNING_SECRET_KEY }}
+          "GIT_AUTHOR_NAME": ${{ secrets.GIT_AUTHOR_NAME }}
+          "GIT_AUTHOR_EMAIL": ${{ secrets.GIT_AUTHOR_EMAIL }}
+
+      - name: "Create Merge-Up Pull Request"
+        uses: "laminas/automatic-releases@v1"
+        with:
+          command-name: "laminas:automatic-releases:create-merge-up-pull-request"
+        env:
+          "GITHUB_TOKEN": ${{ secrets.GITHUB_TOKEN }}
+          "SIGNING_SECRET_KEY": ${{ secrets.SIGNING_SECRET_KEY }}
+          "GIT_AUTHOR_NAME": ${{ secrets.GIT_AUTHOR_NAME }}
+          "GIT_AUTHOR_EMAIL": ${{ secrets.GIT_AUTHOR_EMAIL }}
+
+      - name: "Create and/or Switch to new Release Branch"
+        uses: "laminas/automatic-releases@v1"
+        with:
+          command-name: "laminas:automatic-releases:switch-default-branch-to-next-minor"
+        env:
+          "GITHUB_TOKEN": ${{ secrets.ORGANIZATION_ADMIN_TOKEN }}
+          "SIGNING_SECRET_KEY": ${{ secrets.SIGNING_SECRET_KEY }}
+          "GIT_AUTHOR_NAME": ${{ secrets.GIT_AUTHOR_NAME }}
+          "GIT_AUTHOR_EMAIL": ${{ secrets.GIT_AUTHOR_EMAIL }}
+
+      - name: "Create new milestones"
+        uses: "laminas/automatic-releases@v1"
+        with:
+          command-name: "laminas:automatic-releases:create-milestones"
+        env:
+          "GITHUB_TOKEN": ${{ secrets.GITHUB_TOKEN }}
+          "SIGNING_SECRET_KEY": ${{ secrets.SIGNING_SECRET_KEY }}
+          "GIT_AUTHOR_NAME": ${{ secrets.GIT_AUTHOR_NAME }}
+          "GIT_AUTHOR_EMAIL": ${{ secrets.GIT_AUTHOR_EMAIL }}

.gitignore

@@ -1 +1,4 @@
 /vendor/
+.env
+/build/
+.phpunit.result.cache

README.md

@@ -8,4 +8,34 @@ Static HTML and PDF generator tool for generating documentation from Markdown fi
 
 ## Usage
 
-TBD
+```bash
+bin/docbook-tool [--html] [--pdf] [--confluence]
+```
+
+For example, this command would generate only the HTML documentation:
+
+```bash
+$ DOCBOOK_TOOL_CONTENT_PATH=/path/to/myproject/docs/book \
+> DOCBOOK_TOOL_TEMPLATE_PATH=/path/to/myproject/docs/template \
+> DOCBOOK_TOOL_OUTPUT_HTML_FILE=/path/to/myproject/build/docs.html \
+> bin/docbook-tool --html
+[2021-01-28T12:28:41.000628+00:00] cli.INFO: Writing HTML output to /path/to/myproject/build/docs.html [] []
+$
+```
+
+## Environment variables
+
+ * `DOCBOOK_TOOL_CONTENT_PATH` - the path where your Markdown documentation is kept (Required)
+   * Example: `/path/to/myproject/docs/book`
+ * `DOCBOOK_TOOL_TEMPLATE_PATH` - the path to your Twig templates called `online.twig` and `pdf.twig` (Required)
+   * Example: `/path/to/myproject/docs/template`
+ * `DOCBOOK_TOOL_FEATURES_PATH` - the base path from where features are stored (Optional)
+   * Example: `/path/to/myproject/features`
+ * `DOCBOOK_TOOL_OUTPUT_HTML_FILE` - where to generate the HTML documentation (Required, if using `--html`)
+   * Example: `/path/to/myproject/build/docs/index.html`
+ * `DOCBOOK_TOOL_OUTPUT_PDF_PATH` - where to generate the PDF files, if used (Required, if using `--pdf`)
+   * Example: `/path/to/myproject/build/docs/pdf`
+ * `DOCBOOK_TOOL_CONFLUENCE_URL` - the base URL of confluence (`/rest/api/content` is appended to this, so don't include that) (Required, if using `--confluence`)
+   * Example: `https://confluence.mycompany.com`
+ * `DOCBOOK_TOOL_CONFLUENCE_AUTH_TOKEN` - the `Authorization` header value to use (Required, if using `--confluence` in a non-interactive terminal)
+   * Example: `Basic bXktdXNlcm5hbWU6bXktcGFzc3dvcmQ=`

bin/docbook-tool.php

@@ -4,6 +4,48 @@
 
 namespace Roave\DocbookTool;
 
-(static function (): void {
-    echo "Hi.\n";
-})();
+use Monolog\Handler\StreamHandler;
+use Monolog\Logger;
+use Roave\DocbookTool\Formatter\AggregatePageFormatter;
+use Roave\DocbookTool\Formatter\ExtractFrontMatter;
+use Roave\DocbookTool\Formatter\InlineFeatureFile;
+use Roave\DocbookTool\Formatter\MarkdownToHtml;
+use Roave\DocbookTool\Formatter\RenderPlantUmlDiagramInline;
+use Roave\DocbookTool\Writer\WriterFactory;
+use Twig\Environment as Twig;
+use Twig\Loader\FilesystemLoader;
+
+use function array_map;
+use function is_string;
+
+(static function (array $arguments): void {
+    require_once __DIR__ . '/../vendor/autoload.php';
+
+    $contentPath  = Environment::require('DOCBOOK_TOOL_CONTENT_PATH');
+    $templatePath = Environment::require('DOCBOOK_TOOL_TEMPLATE_PATH');
+    $featuresPath = Environment::optional('DOCBOOK_TOOL_FEATURES_PATH');
+
+    $twig = new Twig(new FilesystemLoader($templatePath));
+
+    $logger = new Logger('cli');
+    $logger->pushHandler(new StreamHandler('php://stdout'));
+
+    $outputWriters = (new WriterFactory($twig, $logger))($arguments);
+
+    $pageFormatters = [
+        new ExtractFrontMatter(),
+        new RenderPlantUmlDiagramInline(),
+        new MarkdownToHtml(),
+    ];
+
+    if (is_string($featuresPath)) {
+        $pageFormatters[] = new InlineFeatureFile($featuresPath);
+    }
+
+    (new WriteAllTheOutputs($outputWriters))(
+        array_map(
+            [new AggregatePageFormatter($pageFormatters), '__invoke'],
+            (new RecursivelyLoadPagesFromPath())($contentPath)
+        )
+    );
+})($argv);

composer.json

@@ -12,12 +12,19 @@
     "require": {
         "php": "8.0.*",
         "guzzlehttp/guzzle": "^7.2",
+        "guzzlehttp/psr7": "^1.7",
         "michelf/php-markdown": "^1.9",
+        "monolog/monolog": "^2.2",
+        "psr/log": "^1.1",
+        "symfony/yaml": "^5.2",
         "thecodingmachine/safe": "^1.3",
-        "twig/twig": "^3.2"
+        "twig/twig": "^3.2",
+        "webmozart/assert": "^1.9"
     },
     "require-dev": {
         "doctrine/coding-standard": "^8.2",
+        "phpunit/phpunit": "^9.5",
+        "psalm/plugin-phpunit": "^0.15.1",
         "roave/security-advisories": "dev-latest",
         "vimeo/psalm": "^4.4"
     },
@@ -28,13 +35,26 @@
     },
     "autoload-dev": {
         "psr-4": {
-            "Roave\\DocbookToolUnitTest\\": "test/unit"
+            "Roave\\DocbookToolIntegrationTest\\": "test/integration"
         }
     },
+    "suggest": {
+        "ext-posix": "Allows interactive entry of Confluence credentials"
+    },
     "bin": [
         "bin/docbook-tool"
     ],
     "config": {
         "sort-packages": true
+    },
+    "scripts": {
+        "post-install-cmd": [
+            "which java",
+            "which wkhtmltopdf"
+        ],
+        "post-update-cmd": [
+            "which java",
+            "which wkhtmltopdf"
+        ]
     }
 }