Skip to content

Commit 8367bbf

Browse files
jaapiojaapio
committed
[TASK] Add chapter about live rendering
1 parent 9555354 commit 8367bbf

2 files changed

Lines changed: 100 additions & 89 deletions

File tree

‎Documentation/Howto/RenderingDocs/Index.rst‎

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

4747
.. include:: /_Includes/_LocalRendering.rst.txt
4848

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

@@ -197,3 +108,8 @@ documentation automatically:
197108
- mkdir -p Documentation-GENERATED-temp
198109
- /opt/guides/entrypoint.sh --config=Documentation --no-progress --minimal-test
199110
111+
.. toctree::
112+
:maxdepth: 1
113+
:hidden:
114+
115+
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)