doxygen

doxygen copied to clipboard

Would be nice if yaml syntax highlighting in markdown code blocks is supported.

• What do you mean by markdown code blocks? are these the parts in fenceded code blocks (~~~) ?
• Could you give a reference how this would look like.
• Can you please attach a, small, self contained example (source+configuration file in a tar or zip) that allows us to reproduce this enhancement request / provblem? Please don't add external links as they might not be persistent.

Yes, I mean fenced code blocks. The syntax highlighting is already working e.g. for ~~~cpp or ~~~xml but not for ~~~yaml.

I think in this case the "problem" is that YAML syntax is not supported by doxygen. For cpp it is clear here the doxygen code coloring is used (like it is for other languages as supported by doxygen).

Can you also give a small example of a XML fenced code block? it might be that this some side effect from something else and only some words are highlighted.

• so would be nice to have 2 examples:
  • XML
  • YAML
• in which doxygen version did you see the XML code coloring?

I use version 1.8.13. I don't think the xml coloring is a side effect, it looks pretty good.

Build example:

mkdir build && cd build
cmake ..

Then open doc/html/index.html.

example_doc.zip

Output:

Result of the yaml highlighting could be something like this:

# Comment
map: # Another comment
  sequence:
    - name: "a"
    - name: "b"
    - name: "c"
  value_1: 1
  value_2: 2
  value_3: 3

For XML there is for input only a code lexer (in xmlcode.h: " Only support syntax highlighting of code at the moment."). to implement the code coloring for YAML a new code parser would probably be needed.

There is already a good code parser I use for syntax highlight of NON doxygen supported languages, it is called source-highlight

it would be fine if doxygen would support external code parser as filter-proc… example:

\code{filter:my/path/to/filter.bash}

 … my non standard code…

\endcode

The filter should take the code on stdin and output html on stdout

---

I arrange to use source-highlight like snippet with output in html, and an aliases for import into doxygen documentation

ALIASES += "htmlcode{4}=\b Example from <tt> \1\fileextension </tt> \b → \4  ^^ <div class=\"htmlcode\"> \htmlinclude \1_\3.\2.html </div>"

In my makefile I use

$(top_srcdir)/sbin/source-highlight.bash --dir $(abs_builddir)/docs --regex ErrorNoRaise_example $(abs_srcdir)/*/server.*

The wrapper is quite simple

## usage …
##
## > used in directory "example" to create a "html-output-file" in "docs" directory 
## > from the code between "server_example"
##
## source-highlight.bash --dir docs --regex server_example vb/MyServer.vb

error() {
  echo "ERROR: $@" 1>&2
  [[ -r "$TARGET_FILE" ]] && rm "$TARGET_FILE"
  exit 1
}

usage() {
  error "source-highlight.bash --dir TARGET-DIR --regex REGEX-RANGE SOURCE-FILE..."
}

TARGET_DIR="."
REGEX_RANGE=""
TARGET_FILE=""

while (( $# > 0 )) ; do
  case "$1" in
    --stdout) TARGET_FILE="stdout"
              shift 1
    ;;
    --dir)    TARGET_DIR="$2"
              shift 2
    ;;
    --regex)  REGEX_RANGE="$2"
              shift 2
    ;;
    -*)       usage ;;
    *)        break ;;
  esac
done

test ! -d "$TARGET_DIR" && mkdir -p "$TARGET_DIR"

if [[ "$REGEX_RANGE" != "" ]] ; then
  REGEX_RANGE_CMD="--regex-range \\[$REGEX_RANGE\\]"
else
  REGEX_RANGE_CMD=""
fi

for SOURCE_FILE ; do

  EXTENSION="${SOURCE_FILE##*.}"
  if [[ "$TARGET_FILE" != "stdout" ]] ; then
    TARGET_FILE="${SOURCE_FILE##*/}"
    TARGET_FILE="$TARGET_DIR/${TARGET_FILE%.*}${REGEX_RANGE:+_}${REGEX_RANGE}.$EXTENSION.html"
    TARGET_CMD="--output $TARGET_FILE"
  else
    TARGET_CMD=""
  fi

  test -r "$SOURCE_FILE" || error "SOURCE_FILE='$SOURCE_FILE' not readable"

  [[ "$TARGET_FILE" != "stdout" && -r "$TARGET_FILE" && "$TARGET_FILE" -nt "$SOURCE_FILE" ]] && continue

  echo "work on… $SOURCE_FILE"

  if [[ ! -z "$REGEX_RANGE" ]] ; then
    (( $(grep --fixed-strings --count "[$REGEX_RANGE]" $SOURCE_FILE) != 2 )) && \
      error "range '$REGEX_RANGE' was not found '2' times in '$SOURCE_FILE'"
  fi

  source-highlight $REGEX_RANGE_CMD --data-dir="$NHI1_HOME/etc/lang" --out-format=html-css --input "$SOURCE_FILE" $TARGET_CMD ||
    error "TARGET_FILE='$TARGET_FILE' not createable"

done

exit 0

great suggestion about \code{filter:my/path/to/filter.bash} Should be working for \snippet too

But it can be bothersome to write it in every place if there are many places like these, so I think we also need an additional global setting for custom highlighters per extension, specified in the doxygen config file, like:

SYNTAX_HIGHLIGHTERS+=".yaml:my/path/to/filter.bash"
SYNTAX_HIGHLIGHTERS+=".toml:my/path/to/toml_highlighter"
SYNTAX_HIGHLIGHTERS+=".x|.y|.z:my/path/to/xyz_joint_highlighter"

+1

+1

Fwiw, the pygments package provides another lexer with support for an even wider range of languages (see here). For files, conversion to stdout is a simple as

$ pygmentize -f html something.yml

Myself, I was not able to make this work with an ALIASES definition, as I could not find a way to pipe the argument of an ALIASES definition to a filter (if I understand correctly, @aotto1968's approach inserts preformatted html code generated from stand-alone files in a separate preprocessing step instead).

Having a section of fenced code

\code{.yaml}
# Comment
map: # Another comment
  sequence:
    - name: "a"
    - name: "b"
    - name: "c"
  value_1: 1
  value_2: 2
  value_3: 3
\endcode

highlighted using an approach along the lines of @enerjazzer's suggestion that would allow for

SYNTAX_HIGHLIGHTERS+=".yaml:pygmentize -f html"

(i.e. provide shell command plus arguments) would indeed be great!

It is presumably still possible to create an INPUT_FILTER to preprocess files and stitch content together. Of course, I may be overlooking something?