[flang-commits] [flang] [Documentation] Fix some invalid references in sphinx documentation (PR #68239)
via flang-commits
flang-commits at lists.llvm.org
Thu Oct 5 01:16:50 PDT 2023
https://github.com/cor3ntin updated https://github.com/llvm/llvm-project/pull/68239
>From c880f321e45e7d145809184c5aed0875f54da9ec Mon Sep 17 00:00:00 2001
From: Corentin Jabot <corentinjabot at gmail.com>
Date: Wed, 4 Oct 2023 19:43:46 +0200
Subject: [PATCH 1/2] [Documentation] Fix some invalid references in sphinx
documentation
---
flang/docs/ComplexOperations.md | 9 +-
flang/docs/conf.py | 1 +
...ionDescriptionOnTheDwarfExpressionStack.md | 152 ++++--------------
llvm/docs/PointerAuth.md | 2 +-
llvm/docs/SpeculativeLoadHardening.md | 2 +-
llvm/docs/conf.py | 8 +-
llvm/docs/llvm_slug.py | 13 ++
7 files changed, 60 insertions(+), 127 deletions(-)
create mode 100644 llvm/docs/llvm_slug.py
diff --git a/flang/docs/ComplexOperations.md b/flang/docs/ComplexOperations.md
index d035658b90acd1c..b7d7a0381bc8abe 100644
--- a/flang/docs/ComplexOperations.md
+++ b/flang/docs/ComplexOperations.md
@@ -1,8 +1,9 @@
# Complex Operations
-```{eval-rst}
-.. toctree::
- :local:
+```{contents}
+---
+local:
+---
```
Fortran includes support for complex number types and a set of operators and
@@ -66,7 +67,7 @@ libm functions.
Similarly to the numerical lowering through the math dialect, certain MLIR
optimisations could violate the precise floating point model, so when that is
-requested lowering manually emits calls to libm, rather than going through the
+requested lowering manually emits calls to libm, rather than going through the
MLIR complex dialect.
The ComplexToStandard dialect does still call into libm for some floating
diff --git a/flang/docs/conf.py b/flang/docs/conf.py
index a90343ef8e05e6c..9b4523737374705 100644
--- a/flang/docs/conf.py
+++ b/flang/docs/conf.py
@@ -31,6 +31,7 @@
# Add any paths that contain templates here, relative to this directory.
templates_path = ["_templates"]
+myst_heading_anchors = 6
import sphinx
diff --git a/llvm/docs/AMDGPUDwarfExtensionAllowLocationDescriptionOnTheDwarfExpressionStack/AMDGPUDwarfExtensionAllowLocationDescriptionOnTheDwarfExpressionStack.md b/llvm/docs/AMDGPUDwarfExtensionAllowLocationDescriptionOnTheDwarfExpressionStack/AMDGPUDwarfExtensionAllowLocationDescriptionOnTheDwarfExpressionStack.md
index 1ff0433f80e9b39..88d9a9f8c4b07ef 100644
--- a/llvm/docs/AMDGPUDwarfExtensionAllowLocationDescriptionOnTheDwarfExpressionStack/AMDGPUDwarfExtensionAllowLocationDescriptionOnTheDwarfExpressionStack.md
+++ b/llvm/docs/AMDGPUDwarfExtensionAllowLocationDescriptionOnTheDwarfExpressionStack/AMDGPUDwarfExtensionAllowLocationDescriptionOnTheDwarfExpressionStack.md
@@ -1,88 +1,10 @@
# Allow Location Descriptions on the DWARF Expression Stack <!-- omit in toc -->
-- [1. Extension](#extension)
-- [2. Heterogeneous Computing Devices](#heterogeneous-computing-devices)
-- [3. DWARF 5](#dwarf-5)
- - [3.1 How DWARF Maps Source Language To Hardware](#how-dwarf-maps-source-language-to-hardware)
- - [3.2 Examples](#examples)
- - [3.2.1 Dynamic Array Size](#dynamic-array-size)
- - [3.2.2 Variable Location in Register](#variable-location-in-register)
- - [3.2.3 Variable Location in Memory](#variable-location-in-memory)
- - [3.2.4 Variable Spread Across Different Locations](#variable-spread-across-different-locations)
- - [3.2.5 Offsetting a Composite Location](#offsetting-a-composite-location)
- - [3.2.6 Pointer to Member](#pointer-to-member)
- - [3.2.7 Virtual Base Class](#virtual-base-class)
- - [3.3 Limitations](#limitations)
-- [4. Extension Solution](#extension-solution)
- - [4.1 Location Description](#location-description)
- - [4.2 Stack Location Description Operations](#stack-location-description-operations)
- - [4.3 Examples](#examples-1)
- - [4.3.1 Source Language Variable Spilled to Part of a Vector Register](#source-language-variable-spilled-to-part-of-a-vector-register)
- - [4.3.2 Source Language Variable Spread Across Multiple Vector Registers](#source-language-variable-spread-across-multiple-vector-registers)
- - [4.3.3 Source Language Variable Spread Across Multiple Kinds of Locations](#source-language-variable-spread-across-multiple-kinds-of-locations)
- - [4.3.4 Address Spaces](#address-spaces)
- - [4.3.5 Bit Offsets](#bit-offsets)
- - [4.4 Call Frame Information (CFI)](#call-frame-information-cfi)
- - [4.5 Objects Not In Byte Aligned Global Memory](#objects-not-in-byte-aligned-global-memory)
- - [4.6 Higher Order Operations](#higher-order-operations)
- - [4.7 Objects In Multiple Places](#objects-in-multiple-places)
-- [5. Conclusion](#conclusion)
-- [A. Changes to DWARF Debugging Information Format Version 5](#a-changes-to-dwarf-debugging-information-format-version-5)
- - [A.2 General Description](#a-2-general-description)
- - [A.2.5 DWARF Expressions](#a-2-5-dwarf-expressions)
- - [A.2.5.1 DWARF Expression Evaluation Context](#a-2-5-1-dwarf-expression-evaluation-context)
- - [A.2.5.2 DWARF Expression Value](#a-2-5-2-dwarf-expression-value)
- - [A.2.5.3 DWARF Location Description](#a-2-5-3-dwarf-location-description)
- - [A.2.5.4 DWARF Operation Expressions](#a-2-5-4-dwarf-operation-expressions)
- - [A.2.5.4.1 Stack Operations](#a-2-5-4-1-stack-operations)
- - [A.2.5.4.2 Control Flow Operations](#a-2-5-4-2-control-flow-operations)
- - [A.2.5.4.3 Value Operations](#a-2-5-4-3-value-operations)
- - [A.2.5.4.3.1 Literal Operations](#a-2-5-4-3-1-literal-operations)
- - [A.2.5.4.3.2 Arithmetic and Logical Operations](#a-2-5-4-3-2-arithmetic-and-logical-operations)
- - [A.2.5.4.3.3 Type Conversion Operations](#a-2-5-4-3-3-type-conversion-operations)
- - [A.2.5.4.3.4 Special Value Operations](#a-2-5-4-3-4-special-value-operations)
- - [A.2.5.4.4 Location Description Operations](#a-2-5-4-4-location-description-operations)
- - [A.2.5.4.4.1 General Location Description Operations](#a-2-5-4-4-1-general-location-description-operations)
- - [A.2.5.4.4.2 Undefined Location Description Operations](#a-2-5-4-4-2-undefined-location-description-operations)
- - [A.2.5.4.4.3 Memory Location Description Operations](#a-2-5-4-4-3-memory-location-description-operations)
- - [A.2.5.4.4.4 Register Location Description Operations](#a-2-5-4-4-4-register-location-description-operations)
- - [A.2.5.4.4.5 Implicit Location Description Operations](#a-2-5-4-4-5-implicit-location-description-operations)
- - [A.2.5.4.4.6 Composite Location Description Operations](#a-2-5-4-4-6-composite-location-description-operations)
- - [A.2.5.5 DWARF Location List Expressions](#a-2-5-5-dwarf-location-list-expressions)
- - [A.3 Program Scope Entries](#a-3-program-scope-entries)
- - [A.3.3 Subroutine and Entry Point Entries](#a-3-3-subroutine-and-entry-point-entries)
- - [A.3.3.5 Low-Level Information](#a-3-3-5-low-level-information)
- - [A.3.4 Call Site Entries and Parameters](#a-3-4-call-site-entries-and-parameters)
- - [A.3.4.2 Call Site Parameters](#a-3-4-2-call-site-parameters)
- - [A.3.5 Lexical Block Entries](#a-3-5-lexical-block-entries)
- - [A.4 Data Object and Object List Entries](#a-4-data-object-and-object-list-entries)
- - [A.4.1 Data Object Entries](#a-4-1-data-object-entries)
- - [A.5 Type Entries](#a-5-type-entries)
- - [A.5.7 Structure, Union, Class and Interface Type Entries](#a-5-7-structure-union-class-and-interface-type-entries)
- - [A.5.7.3 Derived or Extended Structures, Classes and Interfaces](#a-5-7-3-derived-or-extended-structures-classes-and-interfaces)
- - [A.5.7.8 Member Function Entries](#a-5-7-8-member-function-entries)
- - [A.5.14 Pointer to Member Type Entries](#a-5-14-pointer-to-member-type-entries)
- - [A.5.16 Dynamic Type Entries](#a-5-16-dynamic-type-entries)
- - [A.6 Other Debugging Information](#a-6-other-debugging-information)
- - [A.6.2 Line Number Information](#a-6-2-line-number-information)
- - [A.6.4 Call Frame Information](#a-6-4-call-frame-information)
- - [A.6.4.1 Structure of Call Frame Information](#a-6-4-1-structure-of-call-frame-information)
- - [A.6.4.2 Call Frame Instructions](#a-6-4-2-call-frame-instructions)
- - [A.6.4.2.1 Row Creation Instructions](#a-6-4-2-1-row-creation-instructions)
- - [A.6.4.2.2 CFA Definition Instructions](#a-6-4-2-2-cfa-definition-instructions)
- - [A.6.4.2.3 Register Rule Instructions](#a-6-4-2-3-register-rule-instructions)
- - [A.6.4.2.4 Row State Instructions](#a-6-4-2-4-row-state-instructions)
- - [A.6.4.2.5 Padding Instruction](#a-6-4-2-5-padding-instruction)
- - [A.6.4.3 Call Frame Instruction Usage](#a-6-4-3-call-frame-instruction-usage)
- - [A.6.4.4 Call Frame Calling Address](#a-6-4-4-call-frame-calling-address)
- - [A.7 Data Representation](#a-7-data-representation)
- - [A.7.4 32-Bit and 64-Bit DWARF Formats](#a-7-4-32-bit-and-64-bit-dwarf-formats)
- - [A.7.5 Format of Debugging Information](#a-7-5-format-of-debugging-information)
- - [A.7.5.5 Classes and Forms](#a-7-5-5-classes-and-forms)
- - [A.7.7 DWARF Expressions](#a-7-7-dwarf-expressions)
- - [A.7.7.1 Operation Expressions](#a-7-7-1-operation-expressions)
- - [A.7.7.3 Location List Expressions](#a-7-7-3-location-list-expressions)
-- [B. Further Information](#b-further-information)
+```{contents}
+---
+local:
+---
+```
# 1. Extension
@@ -111,20 +33,18 @@ specialized context sensitive operations are harder for both producers and
consumers than a smaller number of general composable operations that have
consistent semantics regardless of context.
-First, section [2. Heterogeneous Computing
-Devices](#heterogeneous-computing-devices) describes heterogeneous devices and
-the features they have that are not addressed by DWARF 5. Then section [3. DWARF
-5](#dwarf-5) presents a brief simplified overview of the DWARF 5 expression
+First, section [2. Heterogeneous Computing Devices](#heterogeneous-computing-devices)
+describes heterogeneous devices and the features they have that are not addressed by DWARF 5.
+Then section [3. DWARF5](#dwarf-5) presents a brief simplified overview of the DWARF 5 expression
evaluation model that highlights the difficulties for supporting the
heterogeneous features. Next, section [4. Extension
Solution](#extension-solution) provides an overview of the proposal, using
simplified examples to illustrate how it can address the issues of heterogeneous
devices and also benefit non-heterogeneous devices. Then overall conclusions are
-covered in section [5. Conclusion](#conclusion). Appendix [A. Changes to DWARF
-Debugging Information Format Version
-5](#a-changes-to-dwarf-debugging-information-format-version-5) gives changes
-relative to the DWARF Version 5 standard. Finally, appendix [B. Further
-Information](#b-further-information) has references to further information.
+covered in section [5. Conclusion](#conclusion).
+Appendix [A. Changes to DWARF Debugging Information Format Version 5](#changes-to-dwarf-debugging-information-format-version-5) gives changes
+relative to the DWARF Version 5 standard. Finally, appendix
+[B. Further Information](#further-information) has references to further information.
# 2. Heterogeneous Computing Devices
@@ -625,7 +545,7 @@ Address requested for identifier "x" which is in register $rdi
With location descriptions on the stack, the definition of `DW_OP_use_location`
can be modified by replacing every instance of "address" with "location
-description", as is described in [A.5 Type Entries](#a-5-type-entries).
+description", as is described in [Type Entries](#type-entries).
To implement the fully generalized version of this attribute, GCC would only
need to change the expression from `DW_OP_plus` to `DW_OP_swap,
@@ -811,8 +731,7 @@ $2 = {<A> = <invalid address>, _vptr.B = <optimized out>}
With location descriptions on the stack, the definition of
`DW_OP_data_member_location` can be modified by replacing every instance of
-"address" with "location description", as is described in [A.5 Type
-Entries](#a-5-type-entries).
+"address" with "location description", as is described in [A.5 Type Entries](#type-entries).
To implement the fully generalized version of this attribute, GCC would only
need to change the last operation in the expression from `DW_OP_plus` to
@@ -1406,10 +1325,9 @@ is evaluated, it may be specified whether a value or location description is
required as the result kind.
If a result kind is specified, and the result of the evaluation does not match
-the specified result kind, then the implicit conversions described in [2.5.4.4.3
-Memory Location Description
-Operations](#memory-location-description-operations) are performed if
-valid. Otherwise, the DWARF expression is ill-formed.
+the specified result kind, then the implicit conversions described in
+[2.5.4.4.3 Memory Location Description Operations](#memory-location-description-operations)
+are performed if valid. Otherwise, the DWARF expression is ill-formed.
If the evaluation of a DWARF expression encounters an evaluation error, then the
result is an evaluation error.
@@ -1794,9 +1712,9 @@ Operations represent a postfix operation on a simple stack machine. Each stack
entry can hold either a value or a location description. Operations can act on
entries on the stack, including adding entries and removing entries. If the kind
of a stack entry does not match the kind required by the operation and is not
-implicitly convertible to the required kind (see [2.5.4.4.3 Memory Location
-Description Operations](#memory-location-description-operations)), then
-the DWARF operation expression is ill-formed.
+implicitly convertible to the required kind
+(see [2.5.4.4.3 Memory Location Description Operations](#memory-location-description-operations)),
+then the DWARF operation expression is ill-formed.
Evaluation of an operation expression starts with an empty stack on which the
entries from the initial stack provided by the context are pushed in the order
@@ -1817,9 +1735,8 @@ The result of the evaluation is:
an empty operation expression for this purpose.</i>
- If the top stack entry is a location description, or can be converted to one
- (see [2.5.4.4.3 Memory Location Description
- Operations](#memory-location-description-operations)), then the result
- is that, possibly converted, location description. Any other entries on the
+ (see [2.5.4.4.3 Memory Location Description Operations](#memory-location-description-operations)),
+ then the result is that, possibly converted, location description. Any other entries on the
stack are discarded.
- Otherwise the DWARF expression is ill-formed.
@@ -1828,9 +1745,8 @@ The result of the evaluation is:
- If the current result kind specifies a value, then:
- If the top stack entry is a value, or can be converted to one (see
- [2.5.4.4.3 Memory Location Description
- Operations](#memory-location-description-operations)), then the result is
- that, possibly converted, value. Any other entries on the stack are
+ [2.5.4.4.3 Memory Location Description Operations](#memory-location-description-operations)),
+ then the result is that, possibly converted, value. Any other entries on the stack are
discarded.
- Otherwise the DWARF expression is ill-formed.
- If the current result kind is not specified, then:
@@ -1867,9 +1783,8 @@ stack assume that the top of the stack (most recently added entry) has index 0.
They allow the stack entries to be either a value or location description.
If any stack entry accessed by a stack operation is an incomplete composite
-location description (see [2.5.4.4.6 Composite Location Description
-Operations](#composite-location-description-operations)), then the DWARF
-expression is ill-formed.
+location description (see [2.5.4.4.6 Composite Location Description Operations]
+(#composite-location-description-operations)), then the DWARF expression is ill-formed.
> NOTE: These operations now support stack entries that are values and location
> descriptions.
@@ -2346,9 +2261,8 @@ There are these special value operations currently defined:
undefined location storage or the offset of any bit exceeds the size of the
location storage LS specified by any single location description SL of L.
- See [2.5.4.4.5 Implicit Location Description
- Operations](#implicit-location-description-operations) for special
- rules concerning implicit location descriptions created by the
+ See [2.5.4.4.5 Implicit Location Description Operations](#implicit-location-description-operations)
+ for special rules concerning implicit location descriptions created by the
`DW_OP_implicit_pointer` operation.
5. `DW_OP_xderef`
@@ -2606,8 +2520,8 @@ bit offset equal to V scaled by 8 (the byte size).
If a stack entry is required to be a location description, but it is an implicit
pointer value IPV with the target architecture default address space, then it is
implicitly converted to a location description with one single location
-description specified by IPV. See [2.5.4.4.5 Implicit Location Description
-Operations](#implicit-location-description-operations).
+description specified by IPV. See
+[2.5.4.4.5 Implicit Location Description Operations](#implicit-location-description-operations).
If a stack entry is required to be a value, but it is a location description L
with one memory location description SL in the target architecture default
@@ -3699,8 +3613,7 @@ Frame Description Entries (FDE). There is at least one CIE in every non-empty
value of length must be an integral multiple of the address size specified
in the `address_size` field.
-2. `CIE_id` (4 or 8 bytes, see [7.4 32-Bit and 64-Bit DWARF
- Formats](#32-bit-and-64-bit-dwarf-formats))
+2. `CIE_id` (4 or 8 bytes, see [7.4 32-Bit and 64-Bit DWARF Formats](#bit-and-64-bit-dwarf-formats))
A constant that is used to distinguish CIEs from FDEs.
@@ -3796,8 +3709,7 @@ An FDE contains the following fields, in order:
of the length field plus the value of length must be an integral multiple of
the address size.
-2. `CIE_pointer` (4 or 8 bytes, see [7.4 32-Bit and 64-Bit DWARF
- Formats](#32-bit-and-64-bit-dwarf-formats))
+2. `CIE_pointer` (4 or 8 bytes, see [7.4 32-Bit and 64-Bit DWARF Formats](#bit-and-64-bit-dwarf-formats))
A constant offset into the `.debug_frame` section that denotes the CIE that
is associated with this FDE.
diff --git a/llvm/docs/PointerAuth.md b/llvm/docs/PointerAuth.md
index 02e3b026a8a3b26..c5f195faaa459db 100644
--- a/llvm/docs/PointerAuth.md
+++ b/llvm/docs/PointerAuth.md
@@ -117,7 +117,7 @@ It returns a raw pointer value. It does **not** check that the
signature is valid.
`key` should identify a key that is appropriate for `value`, as defined
-by the target-specific [keys](#key)).
+by the target-specific [keys](#keys)).
If `value` is a raw pointer value, it is returned as-is (provided the `key`
is appropriate for the pointer).
diff --git a/llvm/docs/SpeculativeLoadHardening.md b/llvm/docs/SpeculativeLoadHardening.md
index 50b9ea39a42a393..0b84efb960cd095 100644
--- a/llvm/docs/SpeculativeLoadHardening.md
+++ b/llvm/docs/SpeculativeLoadHardening.md
@@ -1,6 +1,6 @@
# Speculative Load Hardening
-### A Spectre Variant #1 Mitigation Technique
+## A Spectre Variant #1 Mitigation Technique
Author: Chandler Carruth - [chandlerc at google.com](mailto:chandlerc at google.com)
diff --git a/llvm/docs/conf.py b/llvm/docs/conf.py
index cf8a75980b53034..91627918e5447e4 100644
--- a/llvm/docs/conf.py
+++ b/llvm/docs/conf.py
@@ -17,7 +17,7 @@
# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
-# sys.path.insert(0, os.path.abspath('.'))
+sys.path.insert(0, os.path.abspath('.'))
# -- General configuration -----------------------------------------------------
@@ -28,6 +28,12 @@
# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
extensions = ["myst_parser", "sphinx.ext.intersphinx", "sphinx.ext.todo"]
+# Automatic anchors for markdown titles
+from llvm_slug import make_slug
+myst_heading_anchors = 6
+myst_heading_slug_func = make_slug
+
+
# Add any paths that contain templates here, relative to this directory.
templates_path = ["_templates"]
diff --git a/llvm/docs/llvm_slug.py b/llvm/docs/llvm_slug.py
new file mode 100644
index 000000000000000..9140150f13763b4
--- /dev/null
+++ b/llvm/docs/llvm_slug.py
@@ -0,0 +1,13 @@
+# -*- coding: utf-8 -*-
+#
+# LLVM documentation anchor slug formatting
+
+# Some of our markdown documentation numbers section titles
+# This helpers is used by myst to remove that numbering from the anchor links.
+
+from docutils.nodes import make_id
+def make_slug(str):
+ import re
+ str = re.sub(r'^\s*(\w\.)+\w\s', '', str)
+ str = re.sub(r'^\s*\w\.\s', '', str)
+ return make_id(str)
>From 1389205c7d4d6bac39622ab8f36431300e745dbe Mon Sep 17 00:00:00 2001
From: Corentin Jabot <corentinjabot at gmail.com>
Date: Thu, 5 Oct 2023 10:16:33 +0200
Subject: [PATCH 2/2] Formatting
---
llvm/docs/conf.py | 3 ++-
llvm/docs/llvm_slug.py | 7 +++++--
2 files changed, 7 insertions(+), 3 deletions(-)
diff --git a/llvm/docs/conf.py b/llvm/docs/conf.py
index 91627918e5447e4..0a3905201c8592f 100644
--- a/llvm/docs/conf.py
+++ b/llvm/docs/conf.py
@@ -17,7 +17,7 @@
# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
-sys.path.insert(0, os.path.abspath('.'))
+sys.path.insert(0, os.path.abspath("."))
# -- General configuration -----------------------------------------------------
@@ -30,6 +30,7 @@
# Automatic anchors for markdown titles
from llvm_slug import make_slug
+
myst_heading_anchors = 6
myst_heading_slug_func = make_slug
diff --git a/llvm/docs/llvm_slug.py b/llvm/docs/llvm_slug.py
index 9140150f13763b4..9dd8b1cd3f1aacd 100644
--- a/llvm/docs/llvm_slug.py
+++ b/llvm/docs/llvm_slug.py
@@ -6,8 +6,11 @@
# This helpers is used by myst to remove that numbering from the anchor links.
from docutils.nodes import make_id
+
+
def make_slug(str):
import re
- str = re.sub(r'^\s*(\w\.)+\w\s', '', str)
- str = re.sub(r'^\s*\w\.\s', '', str)
+
+ str = re.sub(r"^\s*(\w\.)+\w\s", "", str)
+ str = re.sub(r"^\s*\w\.\s", "", str)
return make_id(str)
More information about the flang-commits
mailing list