Page MenuHomePhabricator

[docs] Convert remaining command guide entries from md to rst.
ClosedPublic

Authored by rupprecht on Aug 15 2019, 10:17 AM.

Details

Summary

Linking between markdown and rst files is currently not supported very well, e.g. the current llvm-addr2line docs [1] link to "llvm-symbolizer" instead of "llvm-symbolizer.html". This is weirdly broken in different ways depending on which versions of sphinx and recommonmark are being used, so workaround the bug by using rst everywhere.

[1] http://llvm.org/docs/CommandGuide/llvm-addr2line.html

Diff Detail

Event Timeline

rupprecht created this revision.Aug 15 2019, 10:17 AM
Herald added a project: Restricted Project. · View Herald TranscriptAug 15 2019, 10:17 AM

Note that despite being a plain translation from md to rst, git doesn't think these are close enough and shows them as deletion+addition instead of moves.

Yay, thank you for working on this!

Unrelated, but i think it would be great for the next step to ensure that
every [installable] binary has a doc/man page,
and ideally require that via tooling for future binaries.

jhenderson added inline comments.Aug 16 2019, 3:42 AM
llvm/docs/CommandGuide/llvm-addr2line.rst
4

Please add .. program:: llvm-addr2line etc to the tops of these files.

8

Here and elsewhere, use :program:'llvm-addr2line' (using backticks instead of apostrophe) etc to match llvm-readelf, llvm-symbolizer etc.

13

Does using the :manpage: link make more sense for the link here, since you use it in the "See Also" block below?

27

--output-style

llvm/docs/CommandGuide/llvm-size.rst
2

"print segment sizes" is factually wrong. llvm-size doesn't look at program headers at all. Perhaps "print size information".

13

Ditto

llvm/docs/CommandGuide/llvm-strings.rst
13

llvm-strings actually prints strings in all files, not just object files.

rupprecht marked 7 inline comments as done.
  • Use :program: rst syntax
  • Correct some mistakes about tool uses
  • Use :manpage: formatted link instead of :doc:
jhenderson added inline comments.Aug 20 2019, 2:05 AM
llvm/docs/CommandGuide/llvm-addr2line.rst
15

Use :program:<program-name> instead of **<program-name>** throughout. Same for other docs.

  • Use :program: syntax everywhere
  • Use `` instead of ** for llvm-ar usage
rupprecht marked 2 inline comments as done.Aug 20 2019, 12:05 PM
rupprecht added inline comments.
llvm/docs/CommandGuide/llvm-addr2line.rst
15

Sorry, didn't realize that worked everywhere.

For the Running **llvm-ranlib** is equivalent to running **llvm-ar s** line, I changed the **llvm-ar s** to ``llvm-ar s`` to be styled more like a code snippet, not a program name (since it's two words). The rest are updated to :program:

This revision is now accepted and ready to land.Aug 21 2019, 1:31 AM
This revision was automatically updated to reflect the committed changes.
rupprecht marked an inline comment as done.