This is an archive of the discontinued LLVM Phabricator instance.

Differential D63873

[docs][tools] Add missing "program" tags to rst files
ClosedPublic

Authored by jhenderson on Jun 27 2019, 4:59 AM.

Details

Reviewers
MaskRay
ikudrin
rupprecht
peter.smith
mtrent
JDevlieghere
andreadb
Commits
rGa056684c3359: [docs][tools] Add missing "program" tags to rst files
rL364538: [docs][tools] Add missing "program" tags to rst files
Summary

Sphinx allows for definitions of command-line options using .. option <name> and references to those options via :option:<name>. However, it looks like there is no scoping of these options by default, meaning that links can end up pointing to incorrect documents. See for example the llvm-mca document, which contains references to -o that point to a different document. What's worse is that these links appear to be non-deterministic in which one is picked (on my machine, some references end up pointing to opt, whereas on the live docs, they point to llvm-dwarfdump, for example).

The fix is to add the .. program <name> tag. This essentially namespaces the options (definitions and references) to the named program, ensuring that the links are kept correct.

Diff Detail

Repository
rL LLVM

Event Timeline

jhenderson created this revision.Jun 27 2019, 4:59 AM
Herald added a reviewer: JDevlieghere. · View Herald TranscriptJun 27 2019, 4:59 AM
Herald added a reviewer: andreadb. · View Herald Transcript
Herald added a project: Restricted Project. · View Herald Transcript
Herald added subscribers: thopre, gbedwell, aprantl. · View Herald Transcript
andreadb accepted this revision.Jun 27 2019, 5:53 AM

LGTM

This revision is now accepted and ready to land.Jun 27 2019, 5:53 AM
Closed by commit rL364538: [docs][tools] Add missing "program" tags to rst files (authored by jhenderson). · Explain WhyJun 27 2019, 6:27 AM
This revision was automatically updated to reflect the committed changes.

Revision Contents

Diff 206848

llvm/trunk/docs/CommandGuide/FileCheck.rst

FileCheck - Flexible pattern matching file verifier FileCheck - Flexible pattern matching file verifier
=================================================== ===================================================
.. program:: FileCheck
SYNOPSIS SYNOPSIS
-------- --------
:program:`FileCheck` *match-filename* [*--check-prefix=XXX*] [*--strict-whitespace*] :program:`FileCheck` *match-filename* [*--check-prefix=XXX*] [*--strict-whitespace*]
DESCRIPTION DESCRIPTION
----------- -----------
▲ Show 20 Lines • Show All 670 Lines • Show Last 20 Lines

llvm/trunk/docs/CommandGuide/bugpoint.rst

bugpoint - automatic test case reduction tool bugpoint - automatic test case reduction tool
============================================= =============================================
.. program:: bugpoint
SYNOPSIS SYNOPSIS
-------- --------
**bugpoint** [*options*] [*input LLVM ll/bc files*] [*LLVM passes*] **--args** **bugpoint** [*options*] [*input LLVM ll/bc files*] [*LLVM passes*] **--args**
*program arguments* *program arguments*
DESCRIPTION DESCRIPTION
----------- -----------
▲ Show 20 Lines • Show All 185 Lines • Show Last 20 Lines

llvm/trunk/docs/CommandGuide/dsymutil.rst

dsymutil - manipulate archived DWARF debug symbol files dsymutil - manipulate archived DWARF debug symbol files
======================================================= =======================================================
.. program:: dsymutil
SYNOPSIS SYNOPSIS
-------- --------
| :program:`dsymutil` [*options*] *executable* | :program:`dsymutil` [*options*] *executable*
DESCRIPTION DESCRIPTION
----------- -----------
▲ Show 20 Lines • Show All 104 Lines • Show Last 20 Lines

llvm/trunk/docs/CommandGuide/lit.rst

lit - LLVM Integrated Tester lit - LLVM Integrated Tester
============================ ============================
.. program:: lit
SYNOPSIS SYNOPSIS
-------- --------
:program:`lit` [*options*] [*tests*] :program:`lit` [*options*] [*tests*]
DESCRIPTION DESCRIPTION
----------- -----------
▲ Show 20 Lines • Show All 471 Lines • Show Last 20 Lines

llvm/trunk/docs/CommandGuide/llc.rst

llc - LLVM static compiler llc - LLVM static compiler
========================== ==========================
.. program:: llc
SYNOPSIS SYNOPSIS
-------- --------
:program:`llc` [*options*] [*filename*] :program:`llc` [*options*] [*filename*]
DESCRIPTION DESCRIPTION
----------- -----------
Show All 24 Lines
End-user Options End-user Options
~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~
.. option:: -help .. option:: -help
Print a summary of command line options. Print a summary of command line options.
.. option:: -o <filename>
Use ``<filename>`` as the output filename. See the summary above for more
details.
.. option:: -O=uint .. option:: -O=uint
Generate code at different optimization levels. These correspond to the Generate code at different optimization levels. These correspond to the
``-O0``, ``-O1``, ``-O2``, and ``-O3`` optimization levels used by ``-O0``, ``-O1``, ``-O2``, and ``-O3`` optimization levels used by
:program:`clang`. :program:`clang`.
.. option:: -mtriple=<target triple> .. option:: -mtriple=<target triple>
▲ Show 20 Lines • Show All 157 Lines • Show Last 20 Lines

llvm/trunk/docs/CommandGuide/lli.rst

lli - directly execute programs from LLVM bitcode lli - directly execute programs from LLVM bitcode
================================================= =================================================
.. program:: lli
SYNOPSIS SYNOPSIS
-------- --------
:program:`lli` [*options*] [*filename*] [*program args*] :program:`lli` [*options*] [*filename*] [*program args*]
DESCRIPTION DESCRIPTION
----------- -----------
▲ Show 20 Lines • Show All 204 Lines • Show Last 20 Lines

llvm/trunk/docs/CommandGuide/llvm-ar.rst

llvm-ar - LLVM archiver llvm-ar - LLVM archiver
======================= =======================
.. program:: llvm-ar
SYNOPSIS SYNOPSIS
-------- --------
**llvm-ar** [-]{dmpqrtx}[Rabfikou] [relpos] [count] <archive> [files...] **llvm-ar** [-]{dmpqrtx}[Rabfikou] [relpos] [count] <archive> [files...]
▲ Show 20 Lines • Show All 356 Lines • Show Last 20 Lines

llvm/trunk/docs/CommandGuide/llvm-as.rst

llvm-as - LLVM assembler llvm-as - LLVM assembler
======================== ========================
.. program:: llvm-as
SYNOPSIS SYNOPSIS
-------- --------
**llvm-as** [*options*] [*filename*] **llvm-as** [*options*] [*filename*]
DESCRIPTION DESCRIPTION
----------- -----------
▲ Show 20 Lines • Show All 45 Lines • Show Last 20 Lines

llvm/trunk/docs/CommandGuide/llvm-bcanalyzer.rst

llvm-bcanalyzer - LLVM bitcode analyzer llvm-bcanalyzer - LLVM bitcode analyzer
======================================= =======================================
.. program:: llvm-bcanalyzer
SYNOPSIS SYNOPSIS
-------- --------
:program:`llvm-bcanalyzer` [*options*] [*filename*] :program:`llvm-bcanalyzer` [*options*] [*filename*]
DESCRIPTION DESCRIPTION
----------- -----------
▲ Show 20 Lines • Show All 294 Lines • Show Last 20 Lines

llvm/trunk/docs/CommandGuide/llvm-build.rst

llvm-build - LLVM Project Build Utility llvm-build - LLVM Project Build Utility
======================================= =======================================
.. program:: llvm-build
SYNOPSIS SYNOPSIS
-------- --------
**llvm-build** [*options*] **llvm-build** [*options*]
▲ Show 20 Lines • Show All 91 Lines • Show Last 20 Lines

llvm/trunk/docs/CommandGuide/llvm-config.rst

llvm-config - Print LLVM compilation options llvm-config - Print LLVM compilation options
============================================ ============================================
.. program:: llvm-config
SYNOPSIS SYNOPSIS
-------- --------
**llvm-config** *option* [*components*...] **llvm-config** *option* [*components*...]
▲ Show 20 Lines • Show All 165 Lines • Show Last 20 Lines

llvm/trunk/docs/CommandGuide/llvm-cov.rst

llvm-cov - emit coverage information llvm-cov - emit coverage information
==================================== ====================================
.. program:: llvm-cov
SYNOPSIS SYNOPSIS
-------- --------
:program:`llvm-cov` *command* [*args...*] :program:`llvm-cov` *command* [*args...*]
DESCRIPTION DESCRIPTION
----------- -----------
▲ Show 20 Lines • Show All 429 Lines • Show Last 20 Lines

llvm/trunk/docs/CommandGuide/llvm-cxxfilt.rst

llvm-cxxfilt - LLVM symbol name demangler llvm-cxxfilt - LLVM symbol name demangler
========================================= =========================================
.. program:: llvm-cxxfilt
SYNOPSIS SYNOPSIS
-------- --------
:program:`llvm-cxxfilt` [*options*] [*mangled names...*] :program:`llvm-cxxfilt` [*options*] [*mangled names...*]
DESCRIPTION DESCRIPTION
----------- -----------
▲ Show 20 Lines • Show All 68 Lines • Show Last 20 Lines

llvm/trunk/docs/CommandGuide/llvm-cxxmap.rst

llvm-cxxmap - Mangled name remapping tool llvm-cxxmap - Mangled name remapping tool
========================================= =========================================
.. program:: llvm-cxxmap
SYNOPSIS SYNOPSIS
-------- --------
:program:`llvm-cxxmap` [*options*] *symbol-file-1* *symbol-file-2* :program:`llvm-cxxmap` [*options*] *symbol-file-1* *symbol-file-2*
DESCRIPTION DESCRIPTION
----------- -----------
▲ Show 20 Lines • Show All 80 Lines • Show Last 20 Lines

llvm/trunk/docs/CommandGuide/llvm-diff.rst

llvm-diff - LLVM structural 'diff' llvm-diff - LLVM structural 'diff'
================================== ==================================
.. program:: llvm-diff
SYNOPSIS SYNOPSIS
-------- --------
**llvm-diff** [*options*] *module 1* *module 2* [*global name ...*] **llvm-diff** [*options*] *module 1* *module 2* [*global name ...*]
▲ Show 20 Lines • Show All 45 Lines • Show Last 20 Lines

llvm/trunk/docs/CommandGuide/llvm-dis.rst

llvm-dis - LLVM disassembler llvm-dis - LLVM disassembler
============================ ============================
.. program:: llvm-dis
SYNOPSIS SYNOPSIS
-------- --------
**llvm-dis** [*options*] [*filename*] **llvm-dis** [*options*] [*filename*]
▲ Show 20 Lines • Show All 58 Lines • Show Last 20 Lines

llvm/trunk/docs/CommandGuide/llvm-dwarfdump.rst

llvm-dwarfdump - dump and verify DWARF debug information llvm-dwarfdump - dump and verify DWARF debug information
======================================================== ========================================================
.. program:: llvm-dwarfdump
SYNOPSIS SYNOPSIS
-------- --------
:program:`llvm-dwarfdump` [*options*] [*filename ...*] :program:`llvm-dwarfdump` [*options*] [*filename ...*]
DESCRIPTION DESCRIPTION
----------- -----------
▲ Show 20 Lines • Show All 161 Lines • Show Last 20 Lines

llvm/trunk/docs/CommandGuide/llvm-exegesis.rst

llvm-exegesis - LLVM Machine Instruction Benchmark llvm-exegesis - LLVM Machine Instruction Benchmark
================================================== ==================================================
.. program:: llvm-exegesis
SYNOPSIS SYNOPSIS
-------- --------
:program:`llvm-exegesis` [*options*] :program:`llvm-exegesis` [*options*]
DESCRIPTION DESCRIPTION
----------- -----------
▲ Show 20 Lines • Show All 254 Lines • Show Last 20 Lines

llvm/trunk/docs/CommandGuide/llvm-extract.rst

llvm-extract - extract a function from an LLVM module llvm-extract - extract a function from an LLVM module
===================================================== =====================================================
.. program:: llvm-extract
SYNOPSIS SYNOPSIS
-------- --------
:program:`llvm-extract` [*options*] **--func** *function-name* [*filename*] :program:`llvm-extract` [*options*] **--func** *function-name* [*filename*]
DESCRIPTION DESCRIPTION
----------- -----------
▲ Show 20 Lines • Show All 68 Lines • Show Last 20 Lines

llvm/trunk/docs/CommandGuide/llvm-lib.rst

llvm-lib - LLVM lib.exe compatible library tool llvm-lib - LLVM lib.exe compatible library tool
=============================================== ===============================================
.. program:: llvm-lib
SYNOPSIS SYNOPSIS
-------- --------
**llvm-lib** [/libpath:<path>] [/out:<output>] [/llvmlibthin] **llvm-lib** [/libpath:<path>] [/out:<output>] [/llvmlibthin]
[/ignore] [/machine] [/nologo] [files...] [/ignore] [/machine] [/nologo] [files...]
Show All 20 Lines

llvm/trunk/docs/CommandGuide/llvm-link.rst

llvm-link - LLVM bitcode linker llvm-link - LLVM bitcode linker
=============================== ===============================
.. program:: llvm-link
SYNOPSIS SYNOPSIS
-------- --------
:program:`llvm-link` [*options*] *filename ...* :program:`llvm-link` [*options*] *filename ...*
DESCRIPTION DESCRIPTION
----------- -----------
▲ Show 20 Lines • Show All 45 Lines • Show Last 20 Lines

llvm/trunk/docs/CommandGuide/llvm-lipo.rst

llvm-lipo - LLVM tool for manipulating universal binaries llvm-lipo - LLVM tool for manipulating universal binaries
========================================================= =========================================================
.. program:: llvm-lipo
SYNOPSIS SYNOPSIS
-------- --------
:program:`llvm-lipo` [*filenames...*] [*options*] :program:`llvm-lipo` [*filenames...*] [*options*]
DESCRIPTION DESCRIPTION
----------- -----------
:program:`llvm-lipo` can create universal binaries from Mach-O files, extract regular object files from universal binaries, and display architecture information about both universal and regular files. :program:`llvm-lipo` can create universal binaries from Mach-O files, extract regular object files from universal binaries, and display architecture information about both universal and regular files.
Show All 28 Lines

llvm/trunk/docs/CommandGuide/llvm-mca.rst

llvm-mca - LLVM Machine Code Analyzer llvm-mca - LLVM Machine Code Analyzer
===================================== =====================================
.. program:: llvm-mca
SYNOPSIS SYNOPSIS
-------- --------
:program:`llvm-mca` [*options*] [input] :program:`llvm-mca` [*options*] [input]
DESCRIPTION DESCRIPTION
----------- -----------
▲ Show 20 Lines • Show All 47 Lines • ▼ Show 20 Lines
to standard output if the input is from standard input. If the :option:`-o` to standard output if the input is from standard input. If the :option:`-o`
option specifies "``-``", then the output will also be sent to standard output. option specifies "``-``", then the output will also be sent to standard output.
.. option:: -help .. option:: -help
Print a summary of command line options. Print a summary of command line options.
.. option:: -o <filename>
Use ``<filename>`` as the output filename. See the summary above for more
details.
.. option:: -mtriple=<target triple> .. option:: -mtriple=<target triple>
Specify a target triple string. Specify a target triple string.
.. option:: -march=<arch> .. option:: -march=<arch>
Specify the architecture for which to analyze the code. It defaults to the Specify the architecture for which to analyze the code. It defaults to the
host default target. host default target.
▲ Show 20 Lines • Show All 759 Lines • Show Last 20 Lines

llvm/trunk/docs/CommandGuide/llvm-nm.rst

llvm-nm - list LLVM bitcode and object file's symbol table llvm-nm - list LLVM bitcode and object file's symbol table
========================================================== ==========================================================
.. program:: llvm-nm
SYNOPSIS SYNOPSIS
-------- --------
:program:`llvm-nm` [*options*] [*filenames...*] :program:`llvm-nm` [*options*] [*filenames...*]
DESCRIPTION DESCRIPTION
----------- -----------
▲ Show 20 Lines • Show All 271 Lines • Show Last 20 Lines

llvm/trunk/docs/CommandGuide/llvm-objdump.rst

llvm-objdump - LLVM's object file dumper llvm-objdump - LLVM's object file dumper
======================================== ========================================
.. program:: llvm-objdump
SYNOPSIS SYNOPSIS
-------- --------
:program:`llvm-objdump` [*commands*] [*options*] [*filenames...*] :program:`llvm-objdump` [*commands*] [*options*] [*filenames...*]
DESCRIPTION DESCRIPTION
----------- -----------
The :program:`llvm-objdump` utility prints the contents of object files and The :program:`llvm-objdump` utility prints the contents of object files and
▲ Show 20 Lines • Show All 320 Lines • Show Last 20 Lines

llvm/trunk/docs/CommandGuide/llvm-pdbutil.rst

llvm-pdbutil - PDB File forensics and diagnostics llvm-pdbutil - PDB File forensics and diagnostics
================================================= =================================================
.. program:: llvm-pdbutil
.. contents:: .. contents::
:local: :local:
Synopsis Synopsis
-------- --------
:program:`llvm-pdbutil` [*subcommand*] [*options*] :program:`llvm-pdbutil` [*subcommand*] [*options*]
▲ Show 20 Lines • Show All 574 Lines • Show Last 20 Lines

llvm/trunk/docs/CommandGuide/llvm-profdata.rst

llvm-profdata - Profile data tool llvm-profdata - Profile data tool
================================= =================================
.. program:: llvm-profdata
SYNOPSIS SYNOPSIS
-------- --------
:program:`llvm-profdata` *command* [*args...*] :program:`llvm-profdata` *command* [*args...*]
DESCRIPTION DESCRIPTION
----------- -----------
▲ Show 20 Lines • Show All 294 Lines • Show Last 20 Lines

llvm/trunk/docs/CommandGuide/llvm-readobj.rst

llvm-readobj - LLVM Object Reader llvm-readobj - LLVM Object Reader
================================= =================================
.. program:: llvm-readobj
SYNOPSIS SYNOPSIS
-------- --------
:program:`llvm-readobj` [*options*] [*input...*] :program:`llvm-readobj` [*options*] [*input...*]
DESCRIPTION DESCRIPTION
----------- -----------
▲ Show 20 Lines • Show All 268 Lines • Show Last 20 Lines

llvm/trunk/docs/CommandGuide/llvm-stress.rst

llvm-stress - generate random .ll files llvm-stress - generate random .ll files
======================================= =======================================
.. program:: llvm-stress
SYNOPSIS SYNOPSIS
-------- --------
:program:`llvm-stress` [-size=filesize] [-seed=initialseed] [-o=outfile] :program:`llvm-stress` [-size=filesize] [-seed=initialseed] [-o=outfile]
DESCRIPTION DESCRIPTION
----------- -----------
Show All 23 Lines

llvm/trunk/docs/CommandGuide/llvm-symbolizer.rst

llvm-symbolizer - convert addresses into source code locations llvm-symbolizer - convert addresses into source code locations
============================================================== ==============================================================
.. program:: llvm-symbolizer
SYNOPSIS SYNOPSIS
-------- --------
:program:`llvm-symbolizer` [*options*] [*addresses...*] :program:`llvm-symbolizer` [*options*] [*addresses...*]
DESCRIPTION DESCRIPTION
----------- -----------
▲ Show 20 Lines • Show All 341 Lines • Show Last 20 Lines

llvm/trunk/docs/CommandGuide/opt.rst

opt - LLVM optimizer opt - LLVM optimizer
==================== ====================
.. program:: opt
SYNOPSIS SYNOPSIS
-------- --------
:program:`opt` [*options*] [*filename*] :program:`opt` [*options*] [*filename*]
DESCRIPTION DESCRIPTION
----------- -----------
▲ Show 20 Lines • Show All 112 Lines • Show Last 20 Lines

llvm/trunk/docs/CommandGuide/tblgen.rst

tblgen - Target Description To C++ Code Generator tblgen - Target Description To C++ Code Generator
================================================= =================================================
.. program:: tblgen
SYNOPSIS SYNOPSIS
-------- --------
:program:`tblgen` [*options*] [*filename*] :program:`tblgen` [*options*] [*filename*]
DESCRIPTION DESCRIPTION
----------- -----------
▲ Show 20 Lines • Show All 134 Lines • Show Last 20 Lines

llvm/trunk/docs/WritingAnLLVMPass.rst

==================== ====================
Writing an LLVM Pass Writing an LLVM Pass
==================== ====================
.. program:: opt
.. contents:: .. contents::
:local: :local:
Introduction --- What is a pass? Introduction --- What is a pass?
================================ ================================
The LLVM Pass Framework is an important part of the LLVM system, because LLVM The LLVM Pass Framework is an important part of the LLVM system, because LLVM
passes are where most of the interesting parts of the compiler exist. Passes passes are where most of the interesting parts of the compiler exist. Passes
▲ Show 20 Lines • Show All 246 Lines • ▼ Show 20 Lines ...
-inferattrs - Infer set function attributes -inferattrs - Infer set function attributes
... ...
The pass name gets added as the information string for your pass, giving some The pass name gets added as the information string for your pass, giving some
documentation to users of :program:`opt`. Now that you have a working pass, documentation to users of :program:`opt`. Now that you have a working pass,
you would go ahead and make it do the cool transformations you want. Once you you would go ahead and make it do the cool transformations you want. Once you
get it all working and tested, it may become useful to find out how fast your get it all working and tested, it may become useful to find out how fast your
pass is. The :ref:`PassManager <writing-an-llvm-pass-passmanager>` provides a pass is. The :ref:`PassManager <writing-an-llvm-pass-passmanager>` provides a
nice command line option (:option:`--time-passes`) that allows you to get nice command line option (:option:`-time-passes`) that allows you to get
information about the execution time of your pass along with the other passes information about the execution time of your pass along with the other passes
you queue up. For example: you queue up. For example:
.. code-block:: console .. code-block:: console
$ opt -load lib/LLVMHello.so -hello -time-passes < hello.bc > /dev/null $ opt -load lib/LLVMHello.so -hello -time-passes < hello.bc > /dev/null
Hello: __main Hello: __main
Hello: puts Hello: puts
▲ Show 20 Lines • Show All 1,159 Lines • Show Last 20 Lines