Documentation | waf: Fix singlehtml output (!104)

[Frank Kuehndel (@frank_k)]

Frank Kuehndel commented on a discussion: https://gitlab.rtems.org/rtems/docs/rtems-docs/-/merge_requests/104#note_120079


@ita2048 I added some printout with `####` into `common/waf.py` to see where `inliner` gets called. For example:

```
        [...]
        so = open(tgt, 'wb')
        se = open(tgt + '.err', 'wb')
           
        # inliner does not handle digests and fails to open the file.
        with open(src, "rb") as fp:
            no_hash = re.sub(b'\\?v=[a-z0-9]{8}', b'', fp.read())
            no_digest = re.sub(b'\\?digest=[a-z0-9]{20}', b'', no_hash)
        with open(src, "wb") as fp:
            fp.write(no_digest)

        print(f"###########################################################")
        print(f"#### 1: {cmd = }")
        r = task.exec_command(cmd, stdout = so, stderr = se, text=True)
        so.close()
        se.close()
```

With `task.exec_command(cmd, stdout = so, stderr = se, text=True)` or `task.exec_command(cmd, stdout = so, text=True)` and with or without binary mode for output files, the relevant output looks like:

```
[...]
###########################################################
#### 1: cmd = '/usr/local/bin/inliner /home/frank/src/rtems-docs/build/user/singlehtml/index.html'
[ 74/170] Compiling common/_static/logo.webp
[ 75/170] Compiling common/_static/custom.css
[ 76/170] Compiling common/_static/favicon.ico
[ 77/170] Compiling build/bsp-howto/singlehtml/index.html
###########################################################
#### 1: cmd = '/usr/local/bin/inliner /home/frank/src/rtems-docs/build/bsp-howto/singlehtml/index.html'



[ 78/170] Compiling common/_static/custom.css
[ 79/170] Compiling common/_static/favicon.ico
[...]
```

That is to say, `task.exec_command()` terminates `inliner` before it even started doing something. Consequently, the produced file `user.html` is empty:

```
(env) frank at 4fad5497bf94:~/src/rtems-docs> ll build/user/singlehtml/
total 1708
drwxr-xr-x 5 frank users    4096 Feb 18 20:01 .
drwxr-xr-x 6 frank users    4096 Feb 18 20:01 ..
-rw-r--r-- 1 frank users     231 Feb 18 20:01 .buildinfo
drwxr-xr-x 2 frank users    4096 Feb 18 20:01 _images
drwxr-xr-x 7 frank users    4096 Feb 18 20:01 _static
drwxr-xr-x 2 frank users    4096 Feb 18 20:00 _templates
-rw-r--r-- 1 frank users 1711997 Feb 18 20:01 index.html
-rw-r--r-- 1 frank users    6283 Feb 18 20:01 objects.inv
-rw-r--r-- 1 frank users       0 Feb 18 20:01 user.html
-rw-r--r-- 1 frank users      28 Feb 18 20:01 user.html.err
```

I also tried the following code which also results in empty singlepage files:

```
        so = open(tgt, 'wb')
        se = open(tgt + '.err', 'wb')

        # inliner does not handle digests and fails to open the file.
        with open(src, "rb") as fp:
            no_hash = re.sub(b'\\?v=[a-z0-9]{8}', b'', fp.read())
            no_digest = re.sub(b'\\?digest=[a-z0-9]{20}', b'', no_hash)
        with open(src, "wb") as fp:
            fp.write(no_digest)

        print(f"###########################################################")
        print(f"#### 1: {cmd = }")
        inliner_out, inliner_err = task.generator.bld.cmd_and_log(cmd, output=BOTH, quiet=BOTH)
        so.write(inliner_out.encode())
        se.write(inliner_err.encode())
        #r = task.exec_command(cmd, stdout = so, stderr = se, text=True)
        r = 0
        so.close()
        se.close()
```

When I invoke `inliner` on the command line I get (and this produces the correct output):

```
(env) frank at 4fad5497bf94:~/src/rtems-docs> /usr/local/bin/inliner /home/frank/src/rtems-docs/build/user/singlehtml/index.html >build/user/singlehtml/user.html
3% remaining: js(14), links(7), favicon(1), styles(1), style-attrs(28), images(33% remaining: js(14), links(7), favicon(1), styles(1), style-attrs(28), images(33% remaining: js(14), links(7), favicon(1), styles(1), style-attrs(28), images(33% remaining: js(14), links(7), favicon(1), styles(1), style-attrs(28), images(33% remaining: js(14), links(7), favicon(1), styles(1), style-attrs(28), images(33% remaining: js(14), links(7), favicon(1), styles(1), style-attrs(28), images(33% remaining: js(14), links(7), favicon(1), styles(1), style-attrs(28), images(33% remaining: js(14), links(7), favicon(1), styles(1), style-attrs(28), images(33% remaining: js(14), links(7), favicon(1), styles(1), style-attrs(28), images(33% remaining: js(14), links(7), favicon(1), styles(1), style-attrs(28), images(33% remaining: js(14), links(7), favicon(1), styles(1), style-attrs(28), images(33% remaining: js(14), links(7), favicon(1), styles(1), style-attrs(28), images(33% remaining: js(14), links(7), favicon(1), styles(1), style-attrs(28), images(33% remaining: js(14), links(7), favicon(1), styles(1), style-attrs(28), images(33% remaining: js(14), links(7), favicon(1), styles(1), style-attrs(28), images(33% remaining: js(14), links(7), favicon(1), styles(1), style-attrs(28), images(33% remaining: js(14), links(7), favicon(1), styles(1), 
[...]
100% remaining: links(-1)
Last job: compressing javascript
Time: 2s 38.722ms
```

I also cross checked with my patch (using `popen()`). It still fixes the problem. Albeit, I needed to add `.encode()` now in

```
        so.write(inliner_output.encode())
```

I guess the Python version changed in the mean time. Today it is `Python 3.12.9`.

-- 
View it on GitLab: https://gitlab.rtems.org/rtems/docs/rtems-docs/-/merge_requests/104#note_120079
You're receiving this email because of your account on gitlab.rtems.org.


-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.rtems.org/pipermail/bugs/attachments/20250218/3b5453ce/attachment-0001.htm>