[all-commits] [llvm/llvm-project] 9cddd7: [clang-format][docs] Add ability to link to specif...

[Emilia Dreamer via All-commits]

  Branch: refs/heads/main
  Home:   https://github.com/llvm/llvm-project
  Commit: 9cddd7a2a1d231bf390679b7bc529c260b4a1e07
      https://github.com/llvm/llvm-project/commit/9cddd7a2a1d231bf390679b7bc529c260b4a1e07
  Author: Emilia Dreamer <emilia at rymiel.space>
  Date:   2023-01-12 (Thu, 12 Jan 2023)

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

  Log Message:
  -----------
  [clang-format][docs] Add ability to link to specific config options

This allows for the creation of permalinks to specific clang-format
options, for better sharing of a specific option and its options.

(I'm adding the usual clang-format reviewers on this patch because
I don't know any other reviewers that well, perhaps someone with
docs experience should be added instead...)

Note that I wanted to make minimal changes to make this happen and thus
landed on an unideal setup, but to me, it seems like the best out of
worse ones.

I could have made every style option a subheading, which would add
automatically the logic for permalinks and the little paragraph icon for
sharing.

However, this meant that the links themselves would be suboptimal, as
they'd include the whole text of the heading, including the type and
versionbadge, which is needless noise and could change, breaking the
concept of a "permalink". The format of the page could be changed to
put the option names on their own in a heading, and the other info below
it in a paragraph.

As Sphinx seems unwilling to fix https://github.com/sphinx-doc/sphinx/issues/1961,
there isn't a succinct way to change the "id" html field used for
sections

I could have used an add-on (https://github.com/GeeTransit/sphinx-better-subsection),
or made one myself, but I wanted to avoid extra dependencies for no
reason. (plus, I don't know how to make one myself.)

I could have used raw HTML for each heading, but that would immensely
pollute the rst file, which, while it is generated, is currently still
human-readable and it'd be nice for it to stay that way.

Also note that sphinx treats references as case-insensitive, which means
that they will all be lowercased in the resulting HTML. I envisioned
the ability to simply add #OptionName after the URL to get placed right
at the desired config option, which isn't possible without things such
as inline `raw` HTML.

To reconcile that, I added the ¶ paragraph buttons that can be used to
generate the link to the desired section, but since headings are not
actually used, they are faked and literally just a link following each
option, which means they stylistically don't match all other headings.

Also note that this sort-of assumes HTML output. I know Sphinx can
output other formats but I do not know if they are used. A non-html
output could embed unusable ¶ signs everywhere.

I'm okay with this patch being rejected in its current solution, or if
any of the above listed alternatives are better, they could be pursued
instead. In case the downsides of this solution are too much, I will
just create a feature request issue for this and maybe let someone more
experienced with Sphinx handle it, since this is still a feature I would
like to have. (and I do not want to deal with Sphinx at all after
battling with it for a whole day to produce a mediocre result.)

Reviewed By: HazardyKnusperkeks, owenpan, MyDeveloperDay, aaron.ballman

Differential Revision: https://reviews.llvm.org/D138446