[all-commits] [llvm/llvm-project] d39a39: [docs][clang-format] Migrate generated clang-forma...

[Reid Kleckner via All-commits]

  Branch: refs/heads/users/rnk/clang-format-md-write
  Home:   https://github.com/llvm/llvm-project
  Commit: d39a39840c5ddbccd82dba05508ccec090818e76
      https://github.com/llvm/llvm-project/commit/d39a39840c5ddbccd82dba05508ccec090818e76
  Author: Reid Kleckner <rkleckner at nvidia.com>
  Date:   2026-08-06 (Thu, 06 Aug 2026)

  Changed paths:
    M clang/docs/ClangFormat.md
    M clang/docs/ClangFormatStyleOptions.md
    M clang/docs/tools/dump_format_help.py
    M clang/docs/tools/dump_format_style.py
    M clang/include/clang/Format/Format.h
    M clang/include/clang/Tooling/Inclusions/IncludeStyle.h

  Log Message:
  -----------
  [docs][clang-format] Migrate generated clang-format docs to markdown

The challenge here is that the documentation is generated from Doxygen
comments in headers, `Format.h` and `IncludeStyle.h`.

First, the generator was updated to generate markdown constructs, and
then the Doxygen comments were also modified to use markdown constructs.
Mostly this means using single backticks instead of double backticks,
which is the Doxygen-native way of expressing code font blocks anyway,
so that's good.

To validate, I built the Sphinx docs and the doxygen, and I confirmed
that the generator script is idempotent, meaning it doesn't change the
markdown output. When I add a new option to clang-format, it shows up in
the help text block, so it works.

Before/after validation links:
| Source file | Before HTML | After HTML |
| --- | --- | --- |
| `clang/docs/ClangFormat.md` | [before](https://clang.llvm.org/docs/ClangFormat.html) | [after](https://llvmdocs.staging.reidkleckner.dev/clang/docs/ClangFormat.html) |
| `clang/docs/ClangFormatStyleOptions.md` | [before](https://clang.llvm.org/docs/ClangFormatStyleOptions.html) | [after](https://llvmdocs.staging.reidkleckner.dev/clang/docs/ClangFormatStyleOptions.html) |

Assisted-by: an agent


  Commit: 0ce2c97157eac1c7f126af817fe1fe9e0854d900
      https://github.com/llvm/llvm-project/commit/0ce2c97157eac1c7f126af817fe1fe9e0854d900
  Author: Reid Kleckner <rkleckner at nvidia.com>
  Date:   2026-08-06 (Thu, 06 Aug 2026)

  Changed paths:
    M clang/docs/ClangFormat.md
    M clang/docs/ClangFormatStyleOptions.md
    M clang/docs/tools/dump_format_style.py

  Log Message:
  -----------
  fix link word wrapping


  Commit: 330f7fdbda24c0ff0a4c21d96583ae1e86056bc4
      https://github.com/llvm/llvm-project/commit/330f7fdbda24c0ff0a4c21d96583ae1e86056bc4
  Author: Reid Kleckner <rkleckner at nvidia.com>
  Date:   2026-08-06 (Thu, 06 Aug 2026)

  Changed paths:
    M clang/docs/ClangFormatStyleOptions.md
    M clang/docs/tools/dump_format_style.py
    M clang/include/clang/Format/Format.h

  Log Message:
  -----------
  Fix dump_format_style.py blank lines and trailing whitespace, regenerate

The reindent_fenced_blocks() change in the previous commit introduced two
output issues when regenerating ClangFormatStyleOptions.md:

1. Empty lines inside code blocks got an indentation prefix added, producing
   trailing whitespace. Fix by skipping the prefix for whitespace-only lines.

2. The blank line that separates a description sentence from the following
   code fence was lost. This blank line is necessary for correct CommonMark
   loose-list rendering. Fix by inserting a blank line before any opening
   code fence (triple-backtick with a lang word, or ::: with a directive)
   that immediately follows a non-blank line.

Regenerate ClangFormatStyleOptions.md with the corrected generator.


Compare: https://github.com/llvm/llvm-project/compare/c5dabf047643...330f7fdbda24

To unsubscribe from these emails, change your notification settings at https://github.com/llvm/llvm-project/settings/notifications