[Buildroot] [RFC PATCH] docs/website: Add Makefile to pre-generate the website

[Buildroot] [RFC PATCH] docs/website: Add Makefile to pre-generate the website

[Ismael Luceno]

Supports the current includes plus smu [0] lightweight markup.

[0] https://github.com/Gottox/smu
Signed-off-by: Ismael Luceno <ismael@iodev.co.uk>
---
 docs/website/Makefile    | 33 +++++++++++++++++++++++++++++++++
 docs/website/incfile.awk | 23 +++++++++++++++++++++++
 2 files changed, 56 insertions(+)
 create mode 100644 docs/website/Makefile
 create mode 100644 docs/website/incfile.awk

diff --git a/docs/website/Makefile b/docs/website/Makefile
new file mode 100644
index 000000000000..b0a56919c0e7
--- /dev/null
+++ b/docs/website/Makefile
@@ -0,0 +1,33 @@
+.PHONY: all
+all:
+
+# Avoid implicit rules
+MAKEFLAGS += -r
+
+AWK ?= mawk
+
+SRCDIR := ${CURDIR}
+DEPLOYDIR := ${CURDIR}/out
+
+src-pages != find ${SRCDIR} -maxdepth 1 -name \*.html -o -name \*.smu
+dst-pages := ${src-pages:${SRCDIR}/%=${DEPLOYDIR}/%}
+dst-pages := ${dst-pages:.smu=.html}
+
+all: ${dst-pages}
+
+conf-files := ${MAKEFILE_LIST}
+conf-files += $(wildcard ${HOME}/.tidyrc)
+conf-files += ${SRCDIR}/incfile.awk
+
+${DEPLOYDIR}/%.html: ${SRCDIR}/%.html ${conf-files}
+	mkdir -p "${@D}"
+	tmpfile=$$(mktemp) && \
+	${AWK} -f incfile.awk $< > "$$tmpfile" && \
+	{ tidy -q -m -i "$$tmpfile"; :; } && \
+	mv "$$tmpfile" $@
+
+${DEPLOYDIR}/%.html: ${SRCDIR}/%.smu ${conf-files}
+	mkdir -p "${@D}"
+	tmpfile=$$(mktemp) && \
+	smu < $< | ${AWK} -f incfile.awk | tidy -q -m > "$$tmpfile" && \
+	mv "$$tmpfile" $@
diff --git a/docs/website/incfile.awk b/docs/website/incfile.awk
new file mode 100644
index 000000000000..350a88e7b956
--- /dev/null
+++ b/docs/website/incfile.awk
@@ -0,0 +1,23 @@
+BEGIN {
+	FS="\""
+}
+
+{
+	do {
+		if (match($0, /^<!--#include file="([^"]*)" *-->$/)) {
+			file_stack[++file_cur] = $2
+		} else {
+			print
+		}
+		if (file_cur) {
+			e = getline < file_stack[file_cur]
+			if (!e) {
+				--file_cur
+			} else if (e == -1) {
+				printf "%s: read error\n", \
+					file_stack[file_cur] \
+					> "/dev/stderr"
+			}
+		}
+	} while (file_cur)
+}
-- 
2.43.0

_______________________________________________
buildroot mailing list
buildroot@buildroot.org
https://lists.buildroot.org/mailman/listinfo/buildroot

Re: [Buildroot] [RFC PATCH] docs/website: Add Makefile to pre-generate the website

[Yann E. MORIN]

Ismael, All,

On 2024-02-06 15:40 +0100, Ismael Luceno spake thusly:
> Supports the current includes plus smu [0] lightweight markup.
> 
> [0] https://github.com/Gottox/smu
> Signed-off-by: Ismael Luceno <ismael@iodev.co.uk>
> ---
[--SNIP--]
> diff --git a/docs/website/Makefile b/docs/website/Makefile
> new file mode 100644
> index 000000000000..b0a56919c0e7
> --- /dev/null
> +++ b/docs/website/Makefile
> @@ -0,0 +1,33 @@
> +.PHONY: all
> +all:
> +
> +# Avoid implicit rules
> +MAKEFLAGS += -r
> +
> +AWK ?= mawk

Make that gawk, so that we can do [0] (see below)

> +SRCDIR := ${CURDIR}

Use parentheses not curly braces, to expand variables in Makefiles,
like we do everyelse in Buildroot: $(..)

(yes, both are valid, but lets be consistent throughout our code base)

> +DEPLOYDIR := ${CURDIR}/out
> +
> +src-pages != find ${SRCDIR} -maxdepth 1 -name \*.html -o -name \*.smu
> +dst-pages := ${src-pages:${SRCDIR}/%=${DEPLOYDIR}/%}
> +dst-pages := ${dst-pages:.smu=.html}
> +
> +all: ${dst-pages}
> +
> +conf-files := ${MAKEFILE_LIST}
> +conf-files += $(wildcard ${HOME}/.tidyrc)
> +conf-files += ${SRCDIR}/incfile.awk
> +
> +${DEPLOYDIR}/%.html: ${SRCDIR}/%.html ${conf-files}
> +	mkdir -p "${@D}"
> +	tmpfile=$$(mktemp) && \
> +	${AWK} -f incfile.awk $< > "$$tmpfile" && \
> +	{ tidy -q -m -i "$$tmpfile"; :; } && \
> +	mv "$$tmpfile" $@
> +
> +${DEPLOYDIR}/%.html: ${SRCDIR}/%.smu ${conf-files}
> +	mkdir -p "${@D}"
> +	tmpfile=$$(mktemp) && \
> +	smu < $< | ${AWK} -f incfile.awk | tidy -q -m > "$$tmpfile" && \

What is the rationale for using smu and tidy to do the deployement?
We don't need/want to minimify the content...

> +	mv "$$tmpfile" $@
> diff --git a/docs/website/incfile.awk b/docs/website/incfile.awk
> new file mode 100644
> index 000000000000..350a88e7b956
> --- /dev/null
> +++ b/docs/website/incfile.awk
> @@ -0,0 +1,23 @@
> +BEGIN {
> +	FS="\""
> +}
> +
> +{
> +	do {
> +		if (match($0, /^<!--#include file="([^"]*)" *-->$/)) {
> +			file_stack[++file_cur] = $2
> +		} else {
> +			print
> +		}
> +		if (file_cur) {
> +			e = getline < file_stack[file_cur]
> +			if (!e) {
> +				--file_cur
> +			} else if (e == -1) {
> +				printf "%s: read error\n", \
> +					file_stack[file_cur] \
> +					> "/dev/stderr"

[0] In case of error, we do want to exit in error and be sure this is
caught at the Makefile level; by using gawk, you can call:

    exit 42

Regards,
Yann E. MORIN.

> +			}
> +		}
> +	} while (file_cur)
> +}
> -- 
> 2.43.0
> 
> _______________________________________________
> buildroot mailing list
> buildroot@buildroot.org
> https://lists.buildroot.org/mailman/listinfo/buildroot

-- 
.-----------------.--------------------.------------------.--------------------.
|  Yann E. MORIN  | Real-Time Embedded | /"\ ASCII RIBBON | Erics' conspiracy: |
| +33 662 376 056 | Software  Designer | \ / CAMPAIGN     |  ___               |
| +33 561 099 427 `------------.-------:  X  AGAINST      |  \e/  There is no  |
| http://ymorin.is-a-geek.org/ | _/*\_ | / \ HTML MAIL    |   v   conspiracy.  |
'------------------------------^-------^------------------^--------------------'
_______________________________________________
buildroot mailing list
buildroot@buildroot.org
https://lists.buildroot.org/mailman/listinfo/buildroot

Re: [Buildroot] [RFC PATCH] docs/website: Add Makefile to pre-generate the website

[Ismael Luceno]

On 06/Feb/2024 16:08, Yann E. MORIN wrote:
<...>
> Make that gawk, so that we can do [0] (see below)

Mawk might be more complete than you think ;-).

> > +SRCDIR := ${CURDIR}
> 
> Use parentheses not curly braces, to expand variables in Makefiles,
> like we do everyelse in Buildroot: $(..)
> 
> (yes, both are valid, but lets be consistent throughout our code base)

OK, I'll change it for v3. I mentioned this before, according to
both GNU and BSD this is legacy syntax, and new stuff should use
curly braces...

<...>
> What is the rationale for using smu and tidy to do the deployement?
> We don't need/want to minimify the content...

smu is for having some markup support, not used for .html files; as
for tidy, it just normalises the html indentation, no minification is
going on.

<...>
> [0] In case of error, we do want to exit in error and be sure this is
> caught at the Makefile level; by using gawk, you can call:
> 
>     exit 42

That also works with any other AWK.
_______________________________________________
buildroot mailing list
buildroot@buildroot.org
https://lists.buildroot.org/mailman/listinfo/buildroot

Re: [Buildroot] [RFC PATCH] docs/website: Add Makefile to pre-generate the website

[Yann E. MORIN]

Ismael, All,

On 2024-02-06 16:21 +0100, Ismael Luceno spake thusly:
> On 06/Feb/2024 16:08, Yann E. MORIN wrote:
[--SNIP--]
> > > +SRCDIR := ${CURDIR}
> > Use parentheses not curly braces, to expand variables in Makefiles,
> > like we do everyelse in Buildroot: $(..)
> > 
> > (yes, both are valid, but lets be consistent throughout our code base)
> OK, I'll change it for v3. I mentioned this before, according to
> both GNU and BSD this is legacy syntax, and new stuff should use
> curly braces...

There is no such deprecation in POSIX:
    https://pubs.opengroup.org/onlinepubs/9699919799/utilities/make.html

> > What is the rationale for using smu and tidy to do the deployement?
> > We don't need/want to minimify the content...
> smu is for having some markup support, not used for .html files; as
> for tidy, it just normalises the html indentation, no minification is
> going on.

As we discussed IRL, there is no reason to run smu, as we have no markup
currently; if we want to add markup in the future, then will be the
moment to add the processing, not now. Ditto, cleanup the files with
tidy, if that is even needed, should be done as a linter step to fixup
the files in the tree, not at deployment time.

> > [0] In case of error, we do want to exit in error and be sure this is
> > caught at the Makefile level; by using gawk, you can call:
> >     exit 42
> That also works with any other AWK.

Ah, right:
    https://pubs.opengroup.org/onlinepubs/9699919799/utilities/awk.html

There is however no requirement on any awk implementation for Buildroot,
then just default to: AWK=awk

Regards,
Yann E. MORIN.

-- 
.-----------------.--------------------.------------------.--------------------.
|  Yann E. MORIN  | Real-Time Embedded | /"\ ASCII RIBBON | Erics' conspiracy: |
| +33 662 376 056 | Software  Designer | \ / CAMPAIGN     |  ___               |
| +33 561 099 427 `------------.-------:  X  AGAINST      |  \e/  There is no  |
| http://ymorin.is-a-geek.org/ | _/*\_ | / \ HTML MAIL    |   v   conspiracy.  |
'------------------------------^-------^------------------^--------------------'
_______________________________________________
buildroot mailing list
buildroot@buildroot.org
https://lists.buildroot.org/mailman/listinfo/buildroot