[DOC] Migrate to TYPO3 documentation rendering

s2b · Aug 2, 2024 · d7da364 · d7da364
1 parent 9d7747a
commit d7da364
Show file tree

Hide file tree

Showing 24 changed files with 616 additions and 326 deletions.
diff --git a/.editorconfig b/.editorconfig
@@ -23,7 +23,6 @@ indent_style = tab
 # ReST-Files
 [*.{rst,rst.txt}]
 indent_size = 4
-max_line_length = 80
 
 # YAML-Files
 [*.{yaml,yml}]

diff --git a/.github/workflows/tests.yaml b/.github/workflows/tests.yaml
@@ -10,6 +10,14 @@ jobs:
       -
         uses: actions/checkout@v4
 
+      -
+        name: Setup PHP
+        uses: shivammathur/setup-php@v2
+        with:
+          php-version: 8.3
+          extensions: intl, mbstring, pdo_sqlite
+          ini-file: development
+
       -
         name: Validate composer.json
         run: composer validate
@@ -62,6 +70,19 @@ jobs:
       unit-coverage-name: coverage-unit-${{ matrix.php-version }}-${{ matrix.typo3-version }}
       functional-coverage-name: coverage-functional-${{ matrix.php-version }}-${{ matrix.typo3-version }}
 
+  test-doc:
+    name: Test documentation rendering
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Test if the documentation will render without warnings
+        run: |
+          mkdir -p Documentation-GENERATED-temp \
+          && docker run --rm --pull always -v $(pwd):/project \
+             ghcr.io/typo3-documentation/render-guides:latest --config=Documentation --no-progress --fail-on-log
+
   coverage:
     needs:
       - test

diff --git a/.gitignore b/.gitignore
@@ -3,3 +3,5 @@
 /.php-cs-fixer.cache
 /var
 /Build/Testing/.phpunit.cache
+/Documentation-GENERATED-temp
+/fluidDocumentationOutput
diff --git a/Build/CodeQuality/.ecrc b/Build/CodeQuality/.ecrc
@@ -11,7 +11,8 @@
         ".DS_Store",
         ".xsd",
         ".php-cs-fixer.cache",
-        "LICENSE"
+        "LICENSE",
+        "ViteAssetCollector.json"
     ],
     "AllowedContentTypes": [],
     "PassedFiles": [],

diff --git a/Build/Documentation/ViewHelpers.json b/Build/Documentation/ViewHelpers.json
@@ -0,0 +1,5 @@
+{
+	"name": "ViteAssetCollector",
+	"namespaceAlias": "vite",
+	"targetNamespace": "http://typo3.org/ns/Praetorius/ViteAssetCollector/ViewHelpers"
+}
diff --git a/Classes/ViewHelpers/Asset/ViteViewHelper.php b/Classes/ViewHelpers/Asset/ViteViewHelper.php
@@ -10,8 +10,31 @@
 use TYPO3Fluid\Fluid\Core\ViewHelper\AbstractViewHelper;
 
 /**
- * This ViewHelper adds frontend assets generated by vite to
- * TYPO3's asset collector
+ * The `asset.vite` ViewHelper embeds all JavaScript and CSS belonging to the
+ * specified vite `entry` using TYPO3's AssetCollector API.
+ *
+ * Example
+ * =======
+ *
+ * ..  code-block:: html
+ *
+ *     <html
+ *         data-namespace-typo3-fluid="true"
+ *         xmlns:vac="http://typo3.org/ns/Praetorius/ViteAssetCollector/ViewHelpers"
+ *     >
+ *
+ *     <vac:asset.vite
+ *         manifest="EXT:sitepackage/Resources/Public/Vite/.vite/manifest.json"
+ *         entry="EXT:sitepackage/Resources/Private/JavaScript/Main.js"
+ *         scriptTagAttributes="{
+ *             type: 'text/javascript',
+ *             async: 1
+ *         }"
+ *         cssTagAttributes="{
+ *             media: 'print'
+ *         }"
+ *         priority="1"
+ *     />
  */
 final class ViteViewHelper extends AbstractViewHelper
 {
@@ -27,21 +50,21 @@ public function initializeArguments(): void
         $this->registerArgument(
             'manifest',
             'string',
-            'Path to vite manifest file; if omitted, default manifest from extension configuration will be used instead.'
+            'Path to your manifest.json file. If omitted, default manifest from extension configuration will be used instead.'
         );
         $this->registerArgument(
             'entry',
             'string',
-            'Name of entrypoint that should be included; can be omitted if manifest file exists and only contains one entrypoint'
+            'Identifier of the desired vite entrypoint; this is the value specified as "input" in the vite configuration file. Can be omitted if manifest file exists and only one entrypoint is present.',
         );
-        $this->registerArgument('devTagAttributes', 'array', 'Additional attributes for dev server script tags.', false, []);
-        $this->registerArgument('scriptTagAttributes', 'array', 'Additional attributes for script tags.', false, []);
-        $this->registerArgument('addCss', 'boolean', 'Define whether css assets should be included.', false, true);
+        $this->registerArgument('devTagAttributes', 'array', 'HTML attributes that should be added to script tags that point to the vite dev server', false, []);
+        $this->registerArgument('scriptTagAttributes', 'array', 'HTML attributes that should be added to script tags for built JavaScript assets', false, []);
+        $this->registerArgument('addCss', 'boolean', 'If set to "false", CSS files associated with the entry point won\'t be added to the asset collector', false, true);
         $this->registerArgument('cssTagAttributes', 'array', 'Additional attributes for css link tags.', false, []);
         $this->registerArgument(
             'priority',
             'boolean',
-            'Define whether the assets should be included before other assets.',
+            'Include assets before other assets in HTML',
             false,
             false
         );

diff --git a/Classes/ViewHelpers/Resource/ViteViewHelper.php b/Classes/ViewHelpers/Resource/ViteViewHelper.php
@@ -10,7 +10,30 @@
 use TYPO3Fluid\Fluid\Core\ViewHelper\AbstractViewHelper;
 
 /**
- * This ViewHelper creates an uri to a specific asset file
+ * The `resource.vite` ViewHelper extracts the uri to one specific asset file from a vite
+ * manifest file. If the dev server is used, the dev server uri to the resource is returned.
+ *
+ * Example
+ * =======
+ *
+ * This can be used to preload certain assets in the HTML `<head>` tag:
+ *
+ * ..  code-block:: html
+ *
+ *     <html
+ *         data-namespace-typo3-fluid="true"
+ *         xmlns:vac="http://typo3.org/ns/Praetorius/ViteAssetCollector/ViewHelpers"
+ *     >
+ *
+ *     <f:section name="HeaderAssets">
+ *         <link
+ *             rel="preload"
+ *             href="{vac:resource.vite(file: 'EXT:sitepackage/Resources/Private/Fonts/webfont.woff2')}"
+ *             as="font"
+ *             type="font/woff2"
+ *             crossorigin
+ *         />
+ *     </f:section>
  */
 final class ViteViewHelper extends AbstractViewHelper
 {
@@ -26,12 +49,12 @@ public function initializeArguments(): void
         $this->registerArgument(
             'manifest',
             'string',
-            'Path to vite manifest file; if omitted, default manifest from extension configuration will be used instead.'
+            'Path to vite manifest file; if omitted, default manifest from extension configuration will be used instead'
         );
         $this->registerArgument(
             'file',
             'string',
-            'Asset file for which uri should be created',
+            'Identifier of the desired asset file for which a uri should be generated',
             true
         );
     }

diff --git a/Documentation/Configuration/Index.rst b/Documentation/Configuration/Index.rst
@@ -0,0 +1,62 @@
+..  include:: /Includes.rst.txt
+
+..  _configuration:
+
+=============
+Configuration
+=============
+
+If you use the default setup, no configuration should be necessary.
+However, you can customize almost everything to create your individual
+development setup.
+
+..  _configuration-devserver:
+
+Adjust vite dev server
+======================
+
+The extension has two configuration options to setup the vite dev server.
+By default, both are set to `auto`, which means:
+
+*   Dev server will only be used in `Development` context
+*   Dev server uri will be determined automatically for environments with
+    `vite-serve for DDEV <https://github.com/torenware/ddev-viteserve>`__ set up
+
+You can adjust both options in your :php:`$TYPO3_CONF_VARS`, for example:
+
+..  code-block:: php
+    :caption: config/system/additional.php
+
+    // Setup vite dev server based on configuration in .env file
+    // TYPO3_VITE_DEV_SERVER='https://localhost:1234'
+    $GLOBALS['TYPO3_CONF_VARS']['EXTENSIONS']['vite_asset_collector']['useDevServer'] = (bool) getenv('TYPO3_VITE_DEV_SERVER');
+    $GLOBALS['TYPO3_CONF_VARS']['EXTENSIONS']['vite_asset_collector']['devServerUri'] = (string) getenv('TYPO3_VITE_DEV_SERVER');
+
+
+..  _configuration-manifest:
+
+Change location of manifest.json
+================================
+
+You can specify the path to vite's `manifest.json` in the extension configuration.
+By default, this is set to `_assets/vite/.vite/manifest.json`, so it will run
+out-of-the-box with vite 5 and the vite TYPO3 plugin.
+
+If you still use vite < 5, you should to change this to `_assets/vite/manifest.json`.
+
+..  code-block:: php
+    :caption: config/system/additional.php
+
+    $GLOBALS['TYPO3_CONF_VARS']['EXTENSIONS']['vite_asset_collector']['defaultManifest'] = 'EXT:sitepackage/Resources/Public/Vite/.vite/manifest.json';
+
+If you change the path here, please be aware that you may need to adjust `outDir` in
+your `vite.config.js` as well:
+
+..  code-block:: javascript
+    :caption: vite.config.js
+
+    export default defineConfig({
+        // ...
+        outDir: 'path/to/sitepackage/Resources/Public/Vite/',
+    })
+
diff --git a/Documentation/DdevSetup.md b/Documentation/DdevSetup.md
diff --git a/Documentation/Includes.rst.txt b/Documentation/Includes.rst.txt
@@ -0,0 +1,34 @@
+..  More information about this file:
+    https://docs.typo3.org/m/typo3/docs-how-to-document/main/en-us/GeneralConventions/FileStructure.html#includes-rst-txt
+
+..  ----------
+..  text roles
+..  ----------
+
+..  role:: aspect(emphasis)
+..  role:: bash(code)
+..  role:: html(code)
+..  role:: js(code)
+..  role:: php(code)
+..  role:: rst(code)
+..  role:: sep(strong)
+..  role:: sql(code)
+
+..  role:: tsconfig(code)
+    :class: typoscript
+
+..  role:: typoscript(code)
+..  role:: xml(code)
+    :class: html
+
+..  role:: yaml(code)
+
+..  default-role:: code
+
+..  ---------
+..  highlight
+..  ---------
+
+..  By default, code blocks use PHP syntax highlighting
+
+..  highlight:: php
diff --git a/Documentation/Index.rst b/Documentation/Index.rst
@@ -0,0 +1,55 @@
+..  include:: /Includes.rst.txt
+
+.. _start:
+
+===================
+Vite AssetCollector
+===================
+
+:Extension key:
+    vite_asset_collector
+
+:Package name:
+    praetorius/vite-asset-collector
+
+:Version:
+    |release|
+
+:Language:
+    en
+
+:Author:
+    Simon Praetorius
+
+:License:
+    This document is published under the
+    `Creative Commons BY 4.0 <https://creativecommons.org/licenses/by/4.0/>`__
+    license.
+
+:Rendered:
+    |today|
+
+----
+
+Vite AssetCollector allows you to use the modern frontend bundler `vite <https://vitejs.dev/>`__
+to build your TYPO3 project's frontend assets.
+
+----
+
+**Table of Contents:**
+
+..  toctree::
+    :maxdepth: 2
+    :titlesonly:
+
+    Introduction/Index
+    Installation/Index
+    Configuration/Index
+    Reference/Index
+
+..  Meta Menu
+
+..  toctree::
+    :hidden:
+
+    Sitemap