Skip to content

Commit 83aa48b

Browse files
jaapiojaapio
committed
[TASK] Add chapter about live rendering
1 parent bca3cf1 commit 83aa48b

2 files changed

Lines changed: 100 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: 95 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,95 @@
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+
Limitations
80+
===========
81+
82+
Not all changes in the source files can be detected automatically, or will
83+
impact the rendered output immediately. In such cases, a manual re-rendering
84+
is required. Examples are:
85+
86+
* Changes in :file:`guides.xml`
87+
* New added files
88+
* Menu changes
89+
* Moving files
90+
91+
.. note::
92+
93+
Please be aware that some editors (like e.g. `VIM`) create temporary files
94+
when opening files for editing. This will not be detected as a change to the
95+
actual file and thus not trigger a re-rendering.

0 commit comments

Comments
 (0)