[llvm-branch-commits] [llvm] [docs] Finish MyST migration for PDB, DirectX, and GlobalISel docs (PR #217159)

[Justin Bogner via llvm-branch-commits]

================
@@ -31,189 +27,189 @@ DX Container data structures are encoded little-endian in the binary file.
 
 The LLVM versions of all data structures described and/or referenced in this
 file are defined in
-`llvm/include/llvm/BinaryFormat/DXContainer.h
-<https://github.com/llvm/llvm-project/blob/main/llvm/include/llvm/BinaryFormat/DXContainer.h>`_.
+[llvm/include/llvm/BinaryFormat/DXContainer.h](https://github.com/llvm/llvm-project/blob/main/llvm/include/llvm/BinaryFormat/DXContainer.h).
 Some pseudo code is provided in blocks below to ease understanding of this
 document, but reading it with the header available will provide the most
 clarity.
 
-File Header
------------
-
-.. code-block:: c
+### File Header
 
-  struct Header {
-    uint8_t Magic[4];
-    uint8_t Digest[16];
-    uint16_t MajorVersion;
-    uint16_t MinorVersion;
-    uint32_t FileSize;
-    uint32_t PartCount;
-  };
+```c
+struct Header {
+  uint8_t Magic[4];
+  uint8_t Digest[16];
+  uint16_t MajorVersion;
+  uint16_t MinorVersion;
+  uint32_t FileSize;
+  uint32_t PartCount;
+};
+```
 
 The DXContainer header matches the pseudo-definition above. It begins with a
-four character code (magic number) with the value ``DXBC`` to denote the file
+four character code (magic number) with the value `DXBC` to denote the file
 format.
 
-The ``Digest`` is a 128bit hash digest computed with a proprietary algorithm and
+The `Digest` is a 128bit hash digest computed with a proprietary algorithm and
 encoded in the binary by the bytecode validator.
 
-The ``MajorVersion`` and ``MinorVersion`` encode the file format version
-``1.0``.
+The `MajorVersion` and `MinorVersion` encode the file format version
+`1.0`.
 
 The remaining fields encode 32-bit unsigned integers for the file size and
 number of parts.
 
-Following the part header is an array of ``PartCount`` 32-bit unsigned integers
+Following the part header is an array of `PartCount` 32-bit unsigned integers
 specifying the offsets of each part header.
 
-Part Data
----------
-
-.. code-block:: c
+### Part Data
 
-  struct PartHeader {
-    uint8_t Name[4];
-    uint32_t Size;
-  }
+```c
+struct PartHeader {
+  uint8_t Name[4];
+  uint32_t Size;
+}
+```
 
 Each part begins with a part header. A part header includes the 4-character part
 name, and a 32-bit unsigned integer specifying the size of the part data. The
-part header is followed by ``Size`` bytes of data comprising the part. The
+part header is followed by `Size` bytes of data comprising the part. The
 format does not explicitly require 32-bit alignment of parts, although LLVM does
 implement this restriction in the writer code (because it's a good idea). The
 LLVM object reader code does not assume inputs are correctly aligned to avoid
 undefined behavior caused by misaligned inputs generated by other compilers.
 
-The :ref:`PRIV <PRIV>` part is an exception: DXContainer writer code in LLVM may
+The {ref}`PRIV <PRIV>` part is an exception: DXContainer writer code in LLVM may
 produce a PRIV part with size which is not a multiple of four bytes.
 
-Part Formats
-============
+## Part Formats
 
 The part name indicates the format of the part data. There are 24 part headers
 used by DXC and FXC. Not all compiled shaders contain all parts. In the list
 below parts generated only by DXC are marked with †, and parts generated only by
 FXC are marked with \*.
 
-#. `DXIL`_† - Stores the DXIL bytecode.
-#. `HASH`_† - Stores the shader MD5 hash.
-#. `ILDB`_† - Stores the DXIL bytecode with LLVM Debug Information embedded in the module.
-#. `ILDN`_† - Stores shader debug name for external debug information.
-#. `ISG1`_ - Stores the input signature for Shader Model 5.1+.
-#. ISGN\* - Stores the input signature for Shader Model 4 and earlier.
-#. `OSG1`_ - Stores the output signature for Shader Model 5.1+.
-#. OSG5\* - Stores the output signature for Shader Model 5.
-#. OSGN\* - Stores the output signature for Shader Model 4 and earlier.
-#. PCSG\* - Stores the patch constant signature for Shader Model 5.1 and earlier.
-#. PDBI† - Stores PDB information.
-#. `PRIV`_† - Stores private data, including embedded companion PDB files.
-#. `PSG1`_ - Stores the patch constant signature for Shader Model 6+.
-#. `PSV0`_ - Stores Pipeline State Validation data.
-#. RDAT† - Stores Runtime Data.
-#. RDEF\* - Stores resource definitions.
-#. `RTS0`_ - Stores compiled root signature.
-#. `SFI0`_ - Stores shader feature flags.
-#. SHDR\* - Stores compiled DXBC bytecode.
-#. SHEX\* - Stores compiled DXBC bytecode.
-#. DXBC\* - Stores compiled DXBC bytecode.
-#. `SRCI`_† - Stores shader source information.
-#. STAT† - Stores shader statistics.
-#. `VERS`_† - Stores shader compiler version information.
-
-DXIL Part
----------
-.. _DXIL:
-
-The DXIL part is comprised of three data structures: the ``ProgramHeader``, the
-``BitcodeHeader`` and the bitcode serialized LLVM 3.7 IR Module.
-
-The ``ProgramHeader`` contains the shader model version and pipeline stage
+01. {ref}`DXIL <DXIL>`† - Stores the DXIL bytecode.
+02. {ref}`HASH <HASH>`† - Stores the shader MD5 hash.
+03. {ref}`ILDB <ILDB>`† - Stores the DXIL bytecode with LLVM Debug Information embedded in the module.
+04. {ref}`ILDN <ILDN>`† - Stores shader debug name for external debug information.
+05. {ref}`ISG1 <ISG1>` - Stores the input signature for Shader Model 5.1+.
+06. ISGN\* - Stores the input signature for Shader Model 4 and earlier.
+07. {ref}`OSG1 <OSG1>` - Stores the output signature for Shader Model 5.1+.
+08. OSG5\* - Stores the output signature for Shader Model 5.
+09. OSGN\* - Stores the output signature for Shader Model 4 and earlier.
+10. PCSG\* - Stores the patch constant signature for Shader Model 5.1 and earlier.
+11. PDBI† - Stores PDB information.
+12. {ref}`PRIV <PRIV>`† - Stores private data, including embedded companion PDB files.
+13. {ref}`PSG1 <PSG1>` - Stores the patch constant signature for Shader Model 6+.
+14. {ref}`PSV0 <PSV0>` - Stores Pipeline State Validation data.
+15. RDAT† - Stores Runtime Data.
+16. RDEF\* - Stores resource definitions.
+17. {ref}`RTS0 <RTS0>` - Stores compiled root signature.
+18. {ref}`SFI0 <SFI0>` - Stores shader feature flags.
+19. SHDR\* - Stores compiled DXBC bytecode.
+20. SHEX\* - Stores compiled DXBC bytecode.
+21. DXBC\* - Stores compiled DXBC bytecode.
+22. {ref}`SRCI <SRCI>`† - Stores shader source information.
+23. STAT† - Stores shader statistics.
+24. {ref}`VERS <VERS>`† - Stores shader compiler version information.
+
+### DXIL Part
+
+(DXIL)=
+
+The DXIL part is comprised of three data structures: the `ProgramHeader`, the
+`BitcodeHeader` and the bitcode serialized LLVM 3.7 IR Module.
+
+The `ProgramHeader` contains the shader model version and pipeline stage
 enumeration value. This identifies the target profile of the contained shader
 bitcode.
 
-The ``BitcodeHeader`` contains the DXIL version information and refers to the
+The `BitcodeHeader` contains the DXIL version information and refers to the
 start of the bitcode data.
 
-HASH Part
----------
-.. _HASH:
+### HASH Part
+
+(HASH)=
 
 The HASH part contains a 32-bit unsigned integer with the shader hash flags, and
-a 128-bit MD5 hash digest. The flags field can either have the value ``0`` to
-indicate no flags, or ``1`` to indicate that the file hash was computed
-including the source code that produced the binary. See :ref:`Compiler Flags
-<compiler_flags>` for how ``/Zss`` and ``/Zsb`` select the hashed bitcode.
+a 128-bit MD5 hash digest. The flags field can either have the value `0` to
+indicate no flags, or `1` to indicate that the file hash was computed
+including the source code that produced the binary. See {ref}`Compiler Flags
+<compiler_flags>` for how `/Zss` and `/Zsb` select the hashed bitcode.
+
+### ILDB Part
 
-ILDB Part
----------
-.. _ILDB:
+(ILDB)=
 
-The ILDB part follows the structure of the `DXIL`_ part. It stores the
+The ILDB part follows the structure of the {ref}`DXIL <DXIL>` part. It stores the
 unstripped DXIL bitcode module with debug information embedded.
 
 The ILDB part is emitted when the shader is compiled with full debug information
-(``/Zi``). It is omitted from all outputs when slim debug (``/Zs``) is used.
-See :ref:`Compiler Flags <compiler_flags>` for how ``/Qembed_debug``,
-``/Qstrip_debug``, ``/Fd``, and ``/Zs`` control whether it appears in the main
+(`/Zi`). It is omitted from all outputs when slim debug (`/Zs`) is used.
+See {ref}`Compiler Flags <compiler_flags>` for how `/Qembed_debug`,
+`/Qstrip_debug`, `/Fd`, and `/Zs` control whether it appears in the main
 output, the companion PDB, or both.
 
-The stripped `DXIL`_ part has the ``Dwarf Version`` and ``Debug Info Version``
-module flags removed, and ``dx.source`` metadata nodes are stripped from it.
-Those nodes are preserved in the ILDB module when ``/Qsource_in_debug_module``
+The stripped {ref}`DXIL <DXIL>` part has the `Dwarf Version` and `Debug Info Version`
+module flags removed, and `dx.source` metadata nodes are stripped from it.
+Those nodes are preserved in the ILDB module when `/Qsource_in_debug_module`
 is used; otherwise they are replaced with empty placeholder values in the ILDB
 module written to the companion PDB file.
 
-.. rubric:: Reading this part
+```{rubric} Reading this part
+```
----------------
bogner wrote:

rubric is weird - might be better to just use a subheader here. I can deal with that in a follow up though, as it will probably change the rendering slightly.

https://github.com/llvm/llvm-project/pull/217159