Skip to content

Commit b7db355

Browse files
jaapiogarvinhicking
jaapio
and
garvinhicking
authored
[TASK] Add chapter about live rendering (#501)
* [TASK] Add chapter about live rendering * [TASK] Add section about docker compose * [TASK] Add ddev section * Apply suggestion from @garvinhicking --------- Co-authored-by: Garvin Hicking <blog@garv.in>
1 parent bca3cf1 commit b7db355

2 files changed

Lines changed: 133 additions & 90 deletions

File tree

‎Documentation/Howto/RenderingDocs/Index.rst‎

Lines changed: 5 additions & 90 deletions
Original file line numberDiff line numberDiff line change
@@ -58,96 +58,6 @@ Make sure that `Docker <https://www.docker.com/>`__ is installed on your system.
5858

5959
.. include:: /_Includes/_LocalRendering.rst.txt
6060

61-
.. _rendering-wysiwyg:
62-
63-
Rendering with more WYSIWYG-feeling (automatic re-rendering)
64-
------------------------------------------------------------
65-
66-
You want to write complex `reST` markup and directly see the
67-
rendered output, browser side-by-side with your editor? Then
68-
this section is for you!
69-
70-
Often, especially in the later stages of creating documentation, you
71-
just edit small parts of the reST files, render the outcome manually
72-
and happily commit your changes.
73-
74-
However, in cases you write larger sections of text, you may want
75-
to get more immediate visual feedback on your changes, but do not
76-
want to manually trigger the rendering time and again.
77-
78-
To make this easier, the project `garvinhicking/typo3-documentation-browsersync
79-
<https://github.com/garvinhicking/typo3-documentation-browsersync>`__
80-
has been created. This docker container solution provides an environment
81-
which permanently watches changes to any of the reST files and automatically
82-
triggers a re-rendering. The generated HTML output is then served with a
83-
local web server (vite-based) in which your browser automatically hot-reloads
84-
all changes and keeps the scroll position.
85-
86-
This allows you to have a browser window next to your reST file editor
87-
to view progress.
88-
89-
Since that whole environment is based on the official
90-
:ref:`TYPO3 documentation rendering container <t3renderguides:start>`
91-
and utilizes a docker container, it is simple to use. Also, all updates
92-
to the `render-guides` project are automatically merged into that
93-
project, so all bugfixes and new features of the PHP-based rendering always
94-
are in sync with this WYSIWYG-project, with a possibility of this becoming
95-
a regular TYPO3-documentation project (given positive feedback).
96-
97-
The project itself has `documentation on the technical details
98-
<https://github.com/garvinhicking/typo3-documentation-browsersync/blob/main/README.md>`__
99-
but all you need is this docker/podman command:
100-
101-
.. tabs::
102-
103-
.. group-tab:: Linux
104-
105-
.. code-block:: bash
106-
107-
docker run --rm -it --pull always \
108-
-v "./Documentation:/project/Documentation" \
109-
-v "./Documentation-GENERATED-temp:/project/Documentation-GENERATED-temp" \
110-
-p 5173:5173 ghcr.io/garvinhicking/typo3-documentation-browsersync:latest
111-
xdg-open "http://localhost:5173/Documentation-GENERATED-temp/Index.html"
112-
113-
.. group-tab:: MacOS
114-
115-
.. code-block:: bash
116-
117-
docker run --rm -it --pull always \
118-
-v "./Documentation:/project/Documentation" \
119-
-v "./Documentation-GENERATED-temp:/project/Documentation-GENERATED-temp" \
120-
-p 5173:5173 ghcr.io/garvinhicking/typo3-documentation-browsersync:latest
121-
open "http://localhost:5173/Documentation-GENERATED-temp/Index.html"
122-
123-
.. group-tab:: Windows
124-
125-
.. code-block:: powershell
126-
127-
docker run --rm -it --pull always \
128-
-v "./Documentation:/project/Documentation" \
129-
-v "./Documentation-GENERATED-temp:/project/Documentation-GENERATED-temp" \
130-
-p 5173:5173 ghcr.io/garvinhicking/typo3-documentation-browsersync:latest
131-
start "http://localhost:5173/Documentation-GENERATED-temp/Index.html"
132-
133-
The command above can also be added to your project's `Makefile` or
134-
you can create a bash alias like:
135-
136-
.. code:: bash
137-
138-
alias render-wysiwyg="docker run --rm -it --pull always \
139-
-v './Documentation:/project/Documentation' \
140-
-v './Documentation-GENERATED-temp:/project/Documentation-GENERATED-temp' \
141-
-p 5173:5173 ghcr.io/garvinhicking/typo3-documentation-browsersync:latest'"
142-
143-
.. note::
144-
145-
If anything on your host operating system already utilizes the TCP port
146-
`5173` you need to adapt that command to use another free TCP port for you,
147-
and adapt the port in the web-browser URL.
148-
149-
.. _publish-documentation:
150-
15161
Publishing extension documentation to docs.typo3.org
15262
====================================================
15363

@@ -213,3 +123,8 @@ documentation automatically:
213123
- mkdir -p Documentation-GENERATED-temp
214124
- /opt/guides/entrypoint.sh --config=Documentation --no-progress --minimal-test
215125
126+
.. toctree::
127+
:maxdepth: 1
128+
:hidden:
129+
130+
Watch

‎Documentation/Howto/RenderingDocs/Watch.rst‎

Lines changed: 128 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,128 @@
1+
:navigation-title: Live rendering (WYSIWYG)
2+
3+
.. _rendering-wysiwyg:
4+
.. _live-rendering:
5+
6+
============================================================
7+
Rendering with more WYSIWYG-feeling (automatic re-rendering)
8+
============================================================
9+
10+
You want to write complex `reST` markup and directly see the
11+
rendered output, browser side-by-side with your editor? Then
12+
this section is for you!
13+
14+
Often, especially in the later stages of creating documentation, you
15+
just edit small parts of the reST files, render the outcome manually
16+
and happily commit your changes.
17+
18+
However, in cases you write larger sections of text, you may want
19+
to get more immediate visual feedback on your changes, but do not
20+
want to manually trigger the rendering time and again.
21+
22+
To make this easier, `render-guides` can serve the rendered documentation
23+
via a local web-server and automatically re-render the documentation
24+
when changes in the source files are detected. This gives you a more
25+
WYSIWYG-like experience when writing documentation.
26+
27+
This allows you to have a browser window next to your reST file editor
28+
to view progress.
29+
30+
.. tabs::
31+
32+
.. group-tab:: Linux
33+
34+
.. code-block:: bash
35+
36+
docker run --rm -it --pull always \
37+
-v "./Documentation:/project/Documentation" \
38+
-v "./Documentation-GENERATED-temp:/project/Documentation-GENERATED-temp" \
39+
-p 1337:1337 ghcr.io/typo3-documentation/render-guides:latest --config="Documentation" --watch
40+
xdg-open "http://localhost:1337/Index.html"
41+
42+
.. group-tab:: MacOS
43+
44+
.. code-block:: bash
45+
46+
docker run --rm -it --pull always \
47+
-v "./Documentation:/project/Documentation" \
48+
-v "./Documentation-GENERATED-temp:/project/Documentation-GENERATED-temp" \
49+
-p 1337:1337 ghcr.io/typo3-documentation/render-guides:latest --config="Documentation" --watch
50+
xdg-open "http://localhost:1337/Index.html"
51+
.. group-tab:: Windows
52+
53+
.. code-block:: powershell
54+
55+
docker run --rm -it --pull always \
56+
-v "./Documentation:/project/Documentation" \
57+
-v "./Documentation-GENERATED-temp:/project/Documentation-GENERATED-temp" \
58+
-p 1337:1337 ghcr.io/typo3-documentation/render-guides:latest --config="Documentation" --watch
59+
xdg-open "http://localhost:1337/Index.html"
60+
61+
The command above can also be added to your project's `Makefile` or
62+
you can create a bash alias like:
63+
64+
.. code:: bash
65+
66+
alias render-wysiwyg="docker run --rm -it --pull always \
67+
-v './Documentation:/project/Documentation' \
68+
-v './Documentation-GENERATED-temp:/project/Documentation-GENERATED-temp' \
69+
-p 1337:1337 ghcr.io/typo3-documentation/render-guides:latest --watch"
70+
71+
.. note::
72+
73+
If anything on your host operating system already utilizes the TCP port
74+
`1337` you need to adapt that command to use another free TCP port for you,
75+
and adapt the port in the web-browser URL.
76+
You can do this by changing the :bash:`-p` parameter, e.g. to
77+
:bash:`-p 8080:1337` to use TCP port `8080` on your host system.
78+
79+
Docker compose
80+
==============
81+
82+
If you are using `docker-compose <https://docs.docker.com/compose/>`_ to manage your
83+
development environment, you can add a service for the live rendering like this:
84+
85+
.. code-block:: yaml
86+
:caption: docker-compose.yml
87+
88+
services:
89+
render-wysiwyg:
90+
restart: "no"
91+
image: ghcr.io/typo3-documentation/render-guides:latest
92+
ports:
93+
- "1337:1337"
94+
volumes:
95+
- ./Documentation:/project/Documentation
96+
- ./Documentation-GENERATED-temp:/project/Documentation-GENERATED-temp
97+
command: ["--config=Documentation", "--watch"]
98+
99+
.. note::
100+
101+
Render guides was never optimized for long running services. You might need
102+
to restart the container from time to time to free up resources.
103+
104+
DDEV
105+
====
106+
107+
For integration with DDEV projects, a DDEV addon has been created at https://github.com/TYPO3-Documentation/ddev-typo3-docs.
108+
This can be used to automatically start the live documentation preview within the DDEV project at http://<yourproject>.ddev.site:1337/
109+
whenever you start that project, and can directly view and work on documentation alongside the project.
110+
In this environment, users do not even need to execute a manual `docker run` command anymore, and have full integration at hand.
111+
112+
Limitations
113+
===========
114+
115+
Not all changes in the source files can be detected automatically, or will
116+
impact the rendered output immediately. In such cases, a manual re-rendering
117+
is required. Examples are:
118+
119+
* Changes in :file:`guides.xml`
120+
* New added files
121+
* Menu changes
122+
* Moving files
123+
124+
.. note::
125+
126+
Please be aware that some editors (like e.g. `VIM`) create temporary files
127+
when opening files for editing. This will not be detected as a change to the
128+
actual file and thus not trigger a re-rendering.

0 commit comments

Comments
 (0)