apache / apache/nuttx

docs: "copy" button mangles content of Makefile snippet

Open
#12,000 2 comments 0 reactions 0 assignees View on GitHub
Dominant language
C
Stars
4k
Forks
1.7k
Avg merge
1d 17h
Merged PRs (30d)
237

Description

The rendered docs contain Makefile snippets in some places, e.g.: https://nuttx.apache.org/docs/latest/guides/customapps.html#makefile

The content of the snippet is supposed to be exportable via the "copy" button in the top right corner.
But for the above example only a broken/mangled text is exported:
```

files

Build targets

Compile C Files

(COBJS): %$(OBJEXT): %.c
(call COMPILE, $<, $@)

Add object files to the apps archive

(call ARCHIVE, libapps.a, $(COBJS))

Create directory links

Setup any special pre-build context

Setup any special pre-configuration context

Make the dependency file, Make.deps

(Q) $(MKDEP) $(ROOTDEPPATH) "$(CC)" -- $(CFLAGS) -- $(SRCS) > Make.dep

Clean the results of the last build

(call CLEAN)

Remove the build context and directory links

Restore the directory to its original state

(call DELFILE, Make.dep)

Include dependencies

```

The following details are missing:
* leading `$`
* leading `#`
* some other lines
* indentation (spaces instead of tabs)

The indentation issue is minor, since `make` (and editors) will complain about mangling, anyway.

But the first two issues (especially missing `$`) can really take a lot of time to understand/debug (makefile error messages are sometimes hard to grasp).

It looks like [copybutton.js](https://nuttx.apache.org/docs/latest/_static/copybutton.js) causes the issue:
```js
// get filtered text
let exclude = '.linenos, .gp, .go';
```

The above code snippet causes the removal of all "nodes" with the `.linenos`, `.gp` and `.go` CSS classes.

The `.gp` class seems to be used for the comment characters (`#`) and for `$`.

The `.go` class is used for most assignments.

The above exclusions are configured in `Documentation/conf.py`. They were introduced in
14d311ca0ab4eef693f92ca8ad1f97af098157e5 (with the addition of sphinx's "copy button" feature). I assume, `.go` and `.gp` can be removed without causing issues.

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.