[TASK] Introduce Makefile and command 'make docs'

[linawolf]

This is more convenient then having to copy-paste the command all the time

[garvinhicking]

Generally I like the idea to add that to each repository that uses the new rendering. One could also add a global command individually, so any project could be rendered, but the convenience in this one as a consistent command is nice!

[brotkrueml]

I hope, we don't want to add a Makefile to all manuals?

[linawolf]

I hope, we don't want to add a Makefile to all manuals?

That would be my plan for the official manuals. And I would like to supply a snippet so ppl can add it to their extensions

[brotkrueml]

I hope, we don't want to add a Makefile to all manuals?

That would be my plan for the official manuals. And I would like to supply a snippet so ppl can add it to their extensions

Then we definitly need to provide a solution for Windows users.

[linawolf]

I am using windows, this runs fine on WSL2 and is preinstalled. I don't know of any windows user that develops TYPO3 but does not use WSL2. And this script is not mandatory, just a convenient shortcut

[brotkrueml]

Okay, then go ahead, you have already an approval.

[brotkrueml]

And: Then we should document the way that works every time.

[brotkrueml]

And to copy/paste: I am using Ctrl + R for searching in the zsh/bash history. It is faster than typing "make docs" manually ;-)

[linawolf]

For those who prefere the Docker command it still works as before...

[brotkrueml]

... which is not documented here.

[garvinhicking]

We could theoretically add a composer command that executes docker for the official doc repositories. That would then not have a Make/wsl2/cygwin dependency.

We could also have both of course, but I feel render-guides overdid this already.

Providing a rendering shortcut that is

• used in all official repos
• easy to run
• hides potential complexity in those long "docker run" commands
• documented (couldn't read this yet though!)
• not a requirement
• not hindering alternate rendering ways (local, manual)
• easy to maintain with low overhead

is an improvement to me? I was more used to composer scripts until I joined the project, and I was under the impression "make" was a decission made already.

[brotkrueml]

IMHO Composer scripts should not be used for calling some binary stuff unrelated to PHP itself. There are other ways to do so. If the command is the same for Windows/Linux/Macos, then put it into a file called "render-docs" and that's it.

Just my 2 cents.

[garvinhicking]

We'd have to add render-docs.sh and render-docs.bat then, I think that would be even less elegant than a Makefile or composer script. And clutter some directory if we add more calls to be executed (guides.xml conversion, guides.xml modification, xml linting...). I think we need a central place for it, so either Makefile (as now) or composer. Everything else would have more dependencies (ie "just" or other command runners).