From 83aa48be470e428d1f477b8fe7f21ae28b2c6fb6 Mon Sep 17 00:00:00 2001 From: Jaapio Date: Sun, 26 Oct 2025 14:36:18 +0100 Subject: [PATCH 1/4] [TASK] Add chapter about live rendering --- Documentation/Howto/RenderingDocs/Index.rst | 95 ++------------------- Documentation/Howto/RenderingDocs/Watch.rst | 95 +++++++++++++++++++++ 2 files changed, 100 insertions(+), 90 deletions(-) create mode 100644 Documentation/Howto/RenderingDocs/Watch.rst diff --git a/Documentation/Howto/RenderingDocs/Index.rst b/Documentation/Howto/RenderingDocs/Index.rst index 5d9e99f3..c7c22f93 100644 --- a/Documentation/Howto/RenderingDocs/Index.rst +++ b/Documentation/Howto/RenderingDocs/Index.rst @@ -58,96 +58,6 @@ Make sure that `Docker `__ is installed on your system. .. include:: /_Includes/_LocalRendering.rst.txt -.. _rendering-wysiwyg: - -Rendering with more WYSIWYG-feeling (automatic re-rendering) ------------------------------------------------------------- - -You want to write complex `reST` markup and directly see the -rendered output, browser side-by-side with your editor? Then -this section is for you! - -Often, especially in the later stages of creating documentation, you -just edit small parts of the reST files, render the outcome manually -and happily commit your changes. - -However, in cases you write larger sections of text, you may want -to get more immediate visual feedback on your changes, but do not -want to manually trigger the rendering time and again. - -To make this easier, the project `garvinhicking/typo3-documentation-browsersync -`__ -has been created. This docker container solution provides an environment -which permanently watches changes to any of the reST files and automatically -triggers a re-rendering. The generated HTML output is then served with a -local web server (vite-based) in which your browser automatically hot-reloads -all changes and keeps the scroll position. - -This allows you to have a browser window next to your reST file editor -to view progress. - -Since that whole environment is based on the official -:ref:`TYPO3 documentation rendering container ` -and utilizes a docker container, it is simple to use. Also, all updates -to the `render-guides` project are automatically merged into that -project, so all bugfixes and new features of the PHP-based rendering always -are in sync with this WYSIWYG-project, with a possibility of this becoming -a regular TYPO3-documentation project (given positive feedback). - -The project itself has `documentation on the technical details -`__ -but all you need is this docker/podman command: - -.. tabs:: - - .. group-tab:: Linux - - .. code-block:: bash - - docker run --rm -it --pull always \ - -v "./Documentation:/project/Documentation" \ - -v "./Documentation-GENERATED-temp:/project/Documentation-GENERATED-temp" \ - -p 5173:5173 ghcr.io/garvinhicking/typo3-documentation-browsersync:latest - xdg-open "http://localhost:5173/Documentation-GENERATED-temp/Index.html" - - .. group-tab:: MacOS - - .. code-block:: bash - - docker run --rm -it --pull always \ - -v "./Documentation:/project/Documentation" \ - -v "./Documentation-GENERATED-temp:/project/Documentation-GENERATED-temp" \ - -p 5173:5173 ghcr.io/garvinhicking/typo3-documentation-browsersync:latest - open "http://localhost:5173/Documentation-GENERATED-temp/Index.html" - - .. group-tab:: Windows - - .. code-block:: powershell - - docker run --rm -it --pull always \ - -v "./Documentation:/project/Documentation" \ - -v "./Documentation-GENERATED-temp:/project/Documentation-GENERATED-temp" \ - -p 5173:5173 ghcr.io/garvinhicking/typo3-documentation-browsersync:latest - start "http://localhost:5173/Documentation-GENERATED-temp/Index.html" - -The command above can also be added to your project's `Makefile` or -you can create a bash alias like: - -.. code:: bash - - alias render-wysiwyg="docker run --rm -it --pull always \ - -v './Documentation:/project/Documentation' \ - -v './Documentation-GENERATED-temp:/project/Documentation-GENERATED-temp' \ - -p 5173:5173 ghcr.io/garvinhicking/typo3-documentation-browsersync:latest'" - -.. note:: - - If anything on your host operating system already utilizes the TCP port - `5173` you need to adapt that command to use another free TCP port for you, - and adapt the port in the web-browser URL. - -.. _publish-documentation: - Publishing extension documentation to docs.typo3.org ==================================================== @@ -213,3 +123,8 @@ documentation automatically: - mkdir -p Documentation-GENERATED-temp - /opt/guides/entrypoint.sh --config=Documentation --no-progress --minimal-test +.. toctree:: + :maxdepth: 1 + :hidden: + + Watch diff --git a/Documentation/Howto/RenderingDocs/Watch.rst b/Documentation/Howto/RenderingDocs/Watch.rst new file mode 100644 index 00000000..cff2c537 --- /dev/null +++ b/Documentation/Howto/RenderingDocs/Watch.rst @@ -0,0 +1,95 @@ +:navigation-title: Live rendering (WYSIWYG) + +.. _rendering-wysiwyg: +.. _live-rendering: + +============================================================ +Rendering with more WYSIWYG-feeling (automatic re-rendering) +============================================================ + +You want to write complex `reST` markup and directly see the +rendered output, browser side-by-side with your editor? Then +this section is for you! + +Often, especially in the later stages of creating documentation, you +just edit small parts of the reST files, render the outcome manually +and happily commit your changes. + +However, in cases you write larger sections of text, you may want +to get more immediate visual feedback on your changes, but do not +want to manually trigger the rendering time and again. + +To make this easier, `render-guides` can serve the rendered documentation +via a local web-server and automatically re-render the documentation +when changes in the source files are detected. This gives you a more +WYSIWYG-like experience when writing documentation. + +This allows you to have a browser window next to your reST file editor +to view progress. + +.. tabs:: + + .. group-tab:: Linux + + .. code-block:: bash + + docker run --rm -it --pull always \ + -v "./Documentation:/project/Documentation" \ + -v "./Documentation-GENERATED-temp:/project/Documentation-GENERATED-temp" \ + -p 1337:1337 ghcr.io/typo3-documentation/render-guides:latest --config="Documentation" --watch + xdg-open "http://localhost:1337/Index.html" + + .. group-tab:: MacOS + + .. code-block:: bash + + docker run --rm -it --pull always \ + -v "./Documentation:/project/Documentation" \ + -v "./Documentation-GENERATED-temp:/project/Documentation-GENERATED-temp" \ + -p 1337:1337 ghcr.io/typo3-documentation/render-guides:latest --config="Documentation" --watch + xdg-open "http://localhost:1337/Index.html" + .. group-tab:: Windows + + .. code-block:: powershell + + docker run --rm -it --pull always \ + -v "./Documentation:/project/Documentation" \ + -v "./Documentation-GENERATED-temp:/project/Documentation-GENERATED-temp" \ + -p 1337:1337 ghcr.io/typo3-documentation/render-guides:latest --config="Documentation" --watch + xdg-open "http://localhost:1337/Index.html" + +The command above can also be added to your project's `Makefile` or +you can create a bash alias like: + +.. code:: bash + + alias render-wysiwyg="docker run --rm -it --pull always \ + -v './Documentation:/project/Documentation' \ + -v './Documentation-GENERATED-temp:/project/Documentation-GENERATED-temp' \ + -p 1337:1337 ghcr.io/typo3-documentation/render-guides:latest --watch" + +.. note:: + + If anything on your host operating system already utilizes the TCP port + `1337` you need to adapt that command to use another free TCP port for you, + and adapt the port in the web-browser URL. + You can do this by changing the :bash:`-p` parameter, e.g. to + :bash:`-p 8080:1337` to use TCP port `8080` on your host system. + +Limitations +=========== + +Not all changes in the source files can be detected automatically, or will +impact the rendered output immediately. In such cases, a manual re-rendering +is required. Examples are: + +* Changes in :file:`guides.xml` +* New added files +* Menu changes +* Moving files + +.. note:: + + Please be aware that some editors (like e.g. `VIM`) create temporary files + when opening files for editing. This will not be detected as a change to the + actual file and thus not trigger a re-rendering. From 8774ec3f4f827ba541c6286e37c689b3b05abdf2 Mon Sep 17 00:00:00 2001 From: Jaapio Date: Fri, 31 Oct 2025 15:18:54 +0100 Subject: [PATCH 2/4] [TASK] Add section about docker compose --- Documentation/Howto/RenderingDocs/Watch.rst | 25 +++++++++++++++++++++ 1 file changed, 25 insertions(+) diff --git a/Documentation/Howto/RenderingDocs/Watch.rst b/Documentation/Howto/RenderingDocs/Watch.rst index cff2c537..86ccddc2 100644 --- a/Documentation/Howto/RenderingDocs/Watch.rst +++ b/Documentation/Howto/RenderingDocs/Watch.rst @@ -76,6 +76,31 @@ you can create a bash alias like: You can do this by changing the :bash:`-p` parameter, e.g. to :bash:`-p 8080:1337` to use TCP port `8080` on your host system. +Docker compose +============== + +If you are using `docker-compose `_ to manage your +development environment, you can add a service for the live rendering like this: + +.. code-block:: yaml + :caption: docker-compose.yml + + services: + render-wysiwyg: + restart: "no" + image: ghcr.io/typo3-documentation/render-guides:latest + ports: + - "1337:1337" + volumes: + - ./Documentation:/project/Documentation + - ./Documentation-GENERATED-temp:/project/Documentation-GENERATED-temp + command: ["--config=Documentation", "--watch"] + +.. info:: + + Render guides was never optimized for long running services. You might need + to restart the container from time to time to free up resources. + Limitations =========== From e935e0f651a9724f1f28db3edc5db05732c7aefe Mon Sep 17 00:00:00 2001 From: Jaapio Date: Sun, 2 Nov 2025 20:38:59 +0100 Subject: [PATCH 3/4] [TASK] Add ddev section --- Documentation/Howto/RenderingDocs/Watch.rst | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-) diff --git a/Documentation/Howto/RenderingDocs/Watch.rst b/Documentation/Howto/RenderingDocs/Watch.rst index 86ccddc2..2b857bc8 100644 --- a/Documentation/Howto/RenderingDocs/Watch.rst +++ b/Documentation/Howto/RenderingDocs/Watch.rst @@ -96,11 +96,19 @@ development environment, you can add a service for the live rendering like this: - ./Documentation-GENERATED-temp:/project/Documentation-GENERATED-temp command: ["--config=Documentation", "--watch"] -.. info:: +.. note:: Render guides was never optimized for long running services. You might need to restart the container from time to time to free up resources. +DDev +==== + +For integration with DDEV projects, a DDEV addon has been created at https://github.com/TYPO3-Documentation/ddev-typo3-docs. +This can be used to automatically start the live documentation preview within the DDEV project at http://.ddev.site:1337/ +whenever you start that project, and can directly view and work on documentation alongside the project. +In this environment, users do not even need to execute a manual `docker run` command anymore, and have full integration at hand. + Limitations =========== From a6d9d7aa8576b42cce16cc32c31e699403c65b04 Mon Sep 17 00:00:00 2001 From: Garvin Hicking Date: Tue, 4 Nov 2025 17:00:25 +0100 Subject: [PATCH 4/4] Apply suggestion from @garvinhicking --- Documentation/Howto/RenderingDocs/Watch.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Documentation/Howto/RenderingDocs/Watch.rst b/Documentation/Howto/RenderingDocs/Watch.rst index 2b857bc8..5469c01a 100644 --- a/Documentation/Howto/RenderingDocs/Watch.rst +++ b/Documentation/Howto/RenderingDocs/Watch.rst @@ -101,7 +101,7 @@ development environment, you can add a service for the live rendering like this: Render guides was never optimized for long running services. You might need to restart the container from time to time to free up resources. -DDev +DDEV ==== For integration with DDEV projects, a DDEV addon has been created at https://github.com/TYPO3-Documentation/ddev-typo3-docs.