Enable nitpicking in sphinx documentation build and fix some broken refs

docs/conf.py

@@ -156,6 +156,38 @@ pygments_style = 'default'
 # If true, keep warnings as "system message" paragraphs in the built documents.
 #keep_warnings = False
 
+# warn about all missing references
+nitpicky = True
+nitpick_ignore = {
+        ('py:class', 'datetime'),
+        ('cpp:identifier', 'uint32_t'),
+        ('cpp:identifier', 'uint64_t'),
+        ('cpp:identifier', 'int32_t'),
+        ('cpp:identifier', 'int64_t'),
+
+        # opaque types
+        ('py:class', 'QWidget'),
+        ('py:class', 'HWND'),
+        ('py:class', 'Display'),
+        ('py:class', 'Drawable'),
+        ('py:class', 'xcb_connection_t'),
+        ('py:class', 'xcb_window_t'),
+        ('py:class', 'wl_display'),
+        ('py:class', 'wl_surface'),
+        ('py:class', 'ANativeWindow'),
+        ('py:class', 'NSView'),
+        ('py:class', 'CALayer'),
+        ('py:class', 'NSView'),
+
+        # faux-defined callback types
+        ('py:func', 'ProgressCallback'),
+        ('py:func', 'KillCallback'),
+        ('py:func', 'PreviewWindowCallback'),
+        ('py:func', 'SaveCallback'),
+        ('py:func', 'ReplaceCallback'),
+        ('py:func', 'RevertCallback'),
+}
+
 # If true, `todo` and `todoList` produce output, else they produce nothing.
 todo_include_todos = False
 

docs/how/how_import_export.rst

@@ -10,7 +10,7 @@ In-capture access
 
 The structured data is available through the :doc:`python scripting <../window/python_shell>`. As an example, we look at one function call from a capture:
 
-First we obtain the :py:class:`APIEvent` that we want to examine, as the last event in an action's list of events and find the chunk index it refers to:
+First we obtain the :class:`~renderdoc.APIEvent` that we want to examine, as the last event in an action's list of events and find the chunk index it refers to:
 
    .. highlight:: python
    .. code:: python

docs/python_api/examples/basics.rst

@@ -17,13 +17,13 @@ Some methods like the two above return information which is global and does not
 
 During RenderDoc's replay, you can imagine a cursor that moves back and forth between the start and end of the frame. All requests for information that varies - such as texture and buffer contents, pipeline state, and other information will be relative to the current event.
 
-Every function call within a frame is assigned an ascending ``eventId``, from ``1`` up to as many events as are in the frame. Within the action list returned by :py:meth:`~renderdoc.ReplayController.GetRootActions`, each action contains a list of events in :py:attr:`~renderdoc.ActionDescription.events`. These contain all of the ``eventId`` that immediately preceded the action. The details of the function call can be found by using :py:attr:`~renderdoc.APIEvent.chunkIndex` as an index into the structured data returned from :py:meth:`~renderdoc.GetStructuredFile`. The structured data contains the function name and the complete set of parameters passed to it, with their values.
+Every function call within a frame is assigned an ascending ``eventId``, from ``1`` up to as many events as are in the frame. Within the action list returned by :py:meth:`~renderdoc.ReplayController.GetRootActions`, each action contains a list of events in :py:attr:`~renderdoc.ActionDescription.events`. These contain all of the ``eventId`` that immediately preceded the action. The details of the function call can be found by using :py:attr:`~renderdoc.APIEvent.chunkIndex` as an index into the structured data returned from :py:meth:`~qrenderdoc.CaptureContext.GetStructuredFile`. The structured data contains the function name and the complete set of parameters passed to it, with their values.
 
 To change the current active event and move the cursor, you can call :py:meth:`~renderdoc.ReplayController.SetFrameEvent`. This will move the replay to represent the current state immediately after the given event has executed.
 
 At this point you can use :py:meth:`~renderdoc.ReplayController.GetBufferData` and :py:meth:`~renderdoc.ReplayController.GetTextureData` to obtain the contents of a buffer or texture respectively. The pipeline state can be accessed via ``Get*PipelineState`` for each API - to determine the current capture's pipeline type you can fetch the API properties from :py:meth:`~renderdoc.ReplayController.GetAPIProperties`.
 
-There is also an API-agnostic pipeline abstraction to return information that is the same across APIs. Using :py:meth:`~renderdoc.GetPipelineState` returns a :py:class:`~renderdoc.PipeState` which has accessors for fetching the current vertex buffers, shaders, and colour outputs. This allows you to write generic code that will work on any API that RenderDoc supports. The API-specific pipelines are still available through ``Get*PipelineState``.
+There is also an API-agnostic pipeline abstraction to return information that is the same across APIs. Using :py:meth:`~qrenderdoc.CaptureContext.CurPipelineState` returns a :py:class:`~renderdoc.PipeState` which has accessors for fetching the current vertex buffers, shaders, and colour outputs. This allows you to write generic code that will work on any API that RenderDoc supports. The API-specific pipelines are still available through ``Get*PipelineState``.
 
 For more examples of how to fetch data, see the concrete examples below.
 

docs/python_api/examples/renderdoc_intro.rst

@@ -67,7 +67,7 @@ Before doing anything, we must initialise the replay API. We do that by calling
 
     rd.InitialiseReplay(rd.GlobalEnvironment(), [])
 
-To begin with, we use :py:meth:`~renderdoc.OpenCaptureFile` to obtain a :py:class:`~renderdoc.CaptureFile` instance. This gives us access to control over a capture file at a meta level. For more information see the :py:class:`CaptureFile` reference - the interface can also be used to create.
+To begin with, we use :py:meth:`~renderdoc.OpenCaptureFile` to obtain a :py:class:`~renderdoc.CaptureFile` instance. This gives us access to control over a capture file at a meta level. For more information see the :py:class:`renderdoc.CaptureFile` reference - the interface can also be used to create.
 
 To open a file, use :py:meth:`~renderdoc.CaptureFile.OpenFile` on the :py:class:`~renderdoc.CaptureFile` instance. This function allows conversion from other formats via an importer, but here we'll use it just for opening a regular ``rdc`` file. It returns a :py:class:`~renderdoc.ResultDetails` which can be used to determine what went wrong in the event that there was a problem. We then check that the capture uses an API which can be replayed locally - for example not every platform supports ``D3D11``, so on linux this would return no local replay support.
 

docs/window/annotation_viewer.rst

@@ -118,6 +118,6 @@ This function can be used to filter the visible events, based on their annotatio
 Python access
 -------------
 
-Annotations on commands can be accessed via :py:attr:`renderdoc.APIEvent.annotations`, which is an optional :py:class:`~renderdoc.SDObject` object that can be accessed recursively. Helper functions like :py:meth:`~renderdoc.SDObject.FindChildByKeyPath` can be used to speed up accessing a specific annotation.
+Annotations on commands can be accessed via :attr:`~renderdoc.APIEvent.annotations`, which is an optional :class:`~renderdoc.SDObject` object that can be accessed recursively. Helper functions like :meth:`~renderdoc.SDObject.FindChildByKeyPath` can be used to speed up accessing a specific annotation.
 
-Annotations on objects are available in a similar way through :py:attr:`renderdoc.ResourceDescription.annotations`.
+Annotations on objects are available in a similar way through :attr:`~renderdoc.ResourceDescription.annotations`.

qrenderdoc/Code/Interface/Extensions.h

@@ -1004,7 +1004,7 @@ By default the progress bar has minimum and maximum values of 0 and 100. These c
   DOCUMENT(R"(Reset a progress bar widget.
 
 Rewinds the progress bar's indicator and hides the indicator's label (theme dependent). If you want
-to keep the label visible, call :meth:`SetProgressBarValue(0)` instead. The minimum and maximum values
+to keep the label visible, call :meth:`SetProgressBarValue` with ``0`` instead. The minimum and maximum values
 are not changed.
 
 :param QWidget pbar: the progress bar.

qrenderdoc/Code/Interface/PersistentConfig.h

@@ -91,7 +91,7 @@ struct ShaderProcessingTool
       return output < o.output;
     return false;
   }
-  DOCUMENT(R"(The :class:`KnownShaderTool` identifying which known tool this program is.
+  DOCUMENT(R"(The :class:`~renderdoc.KnownShaderTool` identifying which known tool this program is.
 
 :type: renderdoc.KnownShaderTool
 )");
@@ -305,8 +305,8 @@ DECLARE_REFLECTION_STRUCT(BugReport);
   CONFIG_SETTING_VAL(public, QString, rdcstr, DefaultCaptureSaveDirectory, "")                     \
                                                                                                    \
   DOCUMENT(                                                                                        \
-      "A :class:`ReplayOptions` containing the configured default replay options to use in most "  \
-      "scenarios when no specific options are given.\n"                                            \
+      "A :class:`~renderdoc.ReplayOptions` containing the configured default replay options to "   \
+      "use in most scenarios when no specific options are given.\n"                                \
       "\n:"                                                                                        \
       "type: renderdoc.ReplayOptions");                                                            \
   CONFIG_SETTING(public, QVariant, ReplayOptions, DefaultReplayOptions)                            \
@@ -778,8 +778,8 @@ DECLARE_REFLECTION_STRUCT(BugReport);
                                                                                                    \
   DOCUMENT("");                                                                                    \
   DOCUMENT(                                                                                        \
-      "``False`` if :class:`ResourceUsage` should combine resource usage across marker "           \
-      "boundaries.\n"                                                                              \
+      "``False`` if :class:`~renderdoc.ResourceUsage` should combine resource usage across "       \
+      "marker boundaries.\n"                                                                       \
       "\n:"                                                                                        \
       "Defaults to ``False``."                                                                     \
       ""                                                                                           \
@@ -968,7 +968,7 @@ loading. It can explicitly save and close before relaunching.
 )");
   void Close();
 
-  DOCUMENT("Configures the :class:`Formatter` class with the settings from this config.");
+  DOCUMENT("Configures the internal number formatter class with the settings from this config.");
   void SetupFormatting();
 
   DOCUMENT(R"(Sets the UI style to the value in :data:`UIStyle`.

qrenderdoc/Code/Interface/QRDInterface.h

@@ -337,10 +337,10 @@ This window is retrieved by calling :meth:`CaptureContext.GetEventBrowser`.
   text inside the filter's parameter list up to where the cursor is. The callback should return a
   list of identifiers used for auto-completion.
 
-  The list does not have to be pre-filtered for matches to the :paramref:`params`, that is provided
-  to allow different autocompletion at different stages (e.g. if there are no parameters, you can
-  autocomplete a property, if a property is already present you can autocomplete valid values for
-  it)
+  The list does not have to be pre-filtered for matches to the :paramref:`AutoCompleteCallback.params`,
+  that is provided to allow different autocompletion at different stages (e.g. if there are no
+  parameters, you can autocomplete a property, if a property is already present you can
+  autocomplete valid values for it)
 
   :param CaptureContext context: The current capture context.
   :param str filter: The name of the filter function.
@@ -748,13 +748,13 @@ DOCUMENT(R"(Specifies a type of followed resource for the :class:`TextureViewer`
 .. data:: ReadWrite
 
   The index specifies a resource within the given shader's
-  :data:`read-write resources <~renderdoc.ShaderReflection.readWriteResources>`. The array element
+  :data:`~renderdoc.ShaderReflection.readWriteResources`. The array element
   then specifies the index within that resource's array, if applicable.
 
 .. data:: ReadOnly
 
   The index specifies a resource within the given shader's
-  :data:`read-only resources <~renderdoc.ShaderReflection.readOnlyResources>`. The array element
+  :data:`~renderdoc.ShaderReflection.readOnlyResources`. The array element
   then specifies the index within that resource's array, if applicable.
 
 .. data:: OutputDepthResolve
@@ -882,7 +882,7 @@ If no location is currently selected or there is no current texture, this will r
 :param bool autofit: ``True`` if the zoom level should be auto-calculated continuously to
   automatically fit the texture completely in view.
 :param float zoom: The zoom level as a percentage, with 100% being 1.0. Ignored if
-  :paramref:`autofit` is ``True``.
+  :paramref:`SetZoomLevel.autofit` is ``True``.
 )");
   virtual void SetZoomLevel(bool autofit, float zoom) = 0;
 
@@ -2403,7 +2403,7 @@ been made.
   DOCUMENT(R"(Register that a resource has replaced, so that the UI can be updated to reflect the
 change.
 
-This should be called at the same time as :meth:`ReplayController.ReplaceResource`.
+This should be called at the same time as :meth:`~renderdoc.ReplayController.ReplaceResource`.
 
 :param renderdoc.ResourceId from: The id of the resource being replaced.
 :param renderdoc.ResourceId to: The id of the resource replacing it.
@@ -2413,9 +2413,9 @@ This should be called at the same time as :meth:`ReplayController.ReplaceResourc
   DOCUMENT(R"(Register that a replacement has been removed, so that the UI can be updated to reflect
 the change.
 
-This should be called at the same time as :meth:`ReplayController.RemoveReplacement`.
+This should be called at the same time as :meth:`~renderdoc.ReplayController.RemoveReplacement`.
 
-See :meth:`ReplaceResource`.
+See :meth:`RegisterReplacement`.
 
 :param renderdoc.ResourceId id: The id of the original resource that was previously replaced.
 )");
@@ -2994,7 +2994,7 @@ on the UI thread.
 )");
   virtual IDebugMessageView *GetDebugMessageView() = 0;
 
-  DOCUMENT(R"(Retrieve the current singleton :class:`LogView`.
+  DOCUMENT(R"(Retrieve the current singleton :class:`DiagnosticLogView`.
 
 :return: The current window, which is created (but not shown) it there wasn't one open.
 :rtype: DiagnosticLogView

qrenderdoc/Code/Interface/RemoteHost.h

@@ -66,7 +66,7 @@ public:
       "Ping the host to check current status - if the server is running, connection status, etc.");
   void CheckStatus();
 
-  DOCUMENT(R"(Runs the command specified in :data:`runCommand`. Returns
+  DOCUMENT(R"(Runs the command specified in :meth:`RunCommand`. Returns
 :class:`~renderdoc.ResultDetails` which indicates success or the type of failure.
 
 :return: The result from launching the remote server.
@@ -141,7 +141,7 @@ public:
 
   DOCUMENT(R"(Create a connection to the remote server.
 
-:return: The status of opening the capture, whether success or failure, and a :class:`RemoteServer`
+:return: The status of opening the capture, whether success or failure, and a :class:`~renderdoc.RemoteServer`
   instance if it were successful
 :rtype: Tuple[renderdoc.ResultDetails, renderdoc.RemoteServer]
 )");

renderdoc/api/replay/common_pipestate.h

@@ -612,7 +612,7 @@ descriptors with a secondary counter.
   uint32_t bufferStructCount = 0;
 
   DOCUMENT(R"(The byte size of a single element in the view. Either the byte size of
-:data:`viewFormat`, or the structured buffer element size, as appropriate.
+:data:`format`, or the structured buffer element size, as appropriate.
 
 :type: int
 )");

renderdoc/api/replay/control_types.h

@@ -477,7 +477,7 @@ particular subresource (such as array slice, mip or multi-sampled sample).
 
 .. data:: ResolveSamples
 
-  Value for :data:`sampleIdx` if the samples should be averaged.
+  Value for :data:`Subresource.sample` if the samples should be averaged.
 )");
 struct TextureDisplay
 {

renderdoc/api/replay/renderdoc_replay.h

@@ -408,8 +408,8 @@ well as control the replay and analysis functionality available.
   Not an actual member function - the signature for any ``PreviewWindowCallback`` callbacks.
 
   Called when a preview window could optionally be opened to display some information. It will be
-  called repeatedly with :paramref:`active` set to ``True`` to allow any platform-specific message
-  pumping.
+  called repeatedly with :paramref:`PreviewWindowCallback.active` set to ``True`` to allow any
+  platform-specific message pumping.
 
   :param bool active: ``True`` if a preview window is active/opened, ``False`` if it has closed.
   :return: The windowing data for a preview window, or empty/default values if no window should be
@@ -1068,8 +1068,8 @@ otherwise.
 :param ResourceId buffer: The id of the buffer to use for data. If
   :data:`ConstantBlock.bufferBacked` is ``False`` this is ignored.
 :param int offset: Retrieve buffer contents starting at this byte offset.
-:param int length: Retrieve this many bytes after :paramref:`offset`. May be 0 to fetch the rest of the
-  buffer.
+:param int length: Retrieve this many bytes after :paramref:`GetCBufferVariableContents.offset`.
+  May be 0 to fetch the rest of the buffer.
 :return: The shader variables with their contents.
 :rtype: List[ShaderVariable]
 )");
@@ -2238,7 +2238,7 @@ DOCUMENT(R"(Add a message to RenderDoc's logfile.
   if a debugger is attached, and fatal errors will kill the process after logging.
 :param str project: A short project tag, which should be uppercase and either 3 or 4 characters.
 :param str file: The file where this log message came from.
-:param int line: The line number in :paramref:`file` where this log message came from.
+:param int line: The line number in :paramref:`LogMessage.file` where this log message came from.
 :param str text: The text of the message.
 )");
 extern "C" RENDERDOC_API void RENDERDOC_CC RENDERDOC_LogMessage(LogType type, const rdcstr &project,

renderdoc/api/replay/replay_enums.h

@@ -248,22 +248,22 @@ DOCUMENT(R"(Represents the base type of a shader variable in debugging or consta
 .. data:: ConstantBlock
 
   A reference to a constant block bound to the shader. Variables with this type are stored with
-  opaque contents and should be decoded with :meth:`ShaderVariable.GetBinding`.
+  opaque contents and should be decoded with :meth:`ShaderVariable.GetBindIndex`.
 
 .. data:: ReadOnlyResource
 
   A reference to a read only resource bound to the shader. Variables with this type are stored with
-  opaque contents and should be decoded with :meth:`ShaderVariable.GetBinding`.
+  opaque contents and should be decoded with :meth:`ShaderVariable.GetBindIndex`.
 
 .. data:: ReadWriteResource
 
   A reference to a read/write resource bound to the shader. Variables with this type are stored with
-  opaque contents and should be decoded with :meth:`ShaderVariable.GetBinding`.
+  opaque contents and should be decoded with :meth:`ShaderVariable.GetBindIndex`.
 
 .. data:: Sampler
 
   A reference to a sampler bound to the shader. Variables with this type are stored with opaque
-  contents and should be decoded with :meth:`ShaderVariable.GetBinding`.
+  contents and should be decoded with :meth:`ShaderVariable.GetBindIndex`.
 
 .. data:: Unknown
 
@@ -367,8 +367,8 @@ DOCUMENT(R"(Represents the component type of a channel in a texture or element i
 
 .. data:: Depth
 
-  An opaque value storing depth information, either :data:`floating point <float>` for 32-bit depth
-  values or else :data:`unsigned normalised <UNorm>` for other bit sizes.
+  An opaque value storing depth information, either :data:`Float` for 32-bit depth
+  values or else :data:`UNorm` for other bit sizes.
 
 .. data:: UNormSRGB
 
@@ -2030,7 +2030,7 @@ DOCUMENT(R"(Identifies a shader encoding used to pass shader code to an API.
 .. data:: OpenGLSPIRV
 
   SPIR-V binary shader, as used by OpenGL. This format is technically not distinct from
-  :data:`VulkanSPIRV` but is considered unique here since it really *should* have been a different
+  :data:`SPIRV` but is considered unique here since it really *should* have been a different
   format, and introducing a separation allows better selection of tools automatically.
 
 .. data:: OpenGLSPIRVAsm
@@ -2612,6 +2612,10 @@ DOCUMENT(R"(The stage in a pipeline where a shader runs
 .. data:: Callable
 
   A callable shader, called by shader code via index during ray processing.
+
+.. data:: Invalid
+
+  An invalid/unknown shader stage.
 )");
 enum class ShaderStage : uint8_t
 {
@@ -2644,6 +2648,7 @@ enum class ShaderStage : uint8_t
   Callable,
 
   Count,
+  Invalid = Count,
 };
 
 ITERABLE_OPERATORS(ShaderStage);
@@ -4513,7 +4518,7 @@ DOCUMENT(R"(Specifies a windowing system to use for creating an output window.
 
 .. data:: Xlib
 
-  The windowing data refers to an Xlib window. See :func:`CreateXLibWindowingData`.
+  The windowing data refers to an Xlib window. See :func:`CreateXlibWindowingData`.
 
 .. data:: XCB
 
@@ -4755,7 +4760,7 @@ enum class TextureCategory : uint32_t
 BITMASK_OPERATORS(TextureCategory);
 DECLARE_REFLECTION_ENUM(TextureCategory);
 
-DOCUMENT(R"(A set of flags for ``ShaderStage`` stages
+DOCUMENT(R"(A set of flags for :class:`ShaderStage` stages
 
 .. data:: Unknown
 
@@ -4880,7 +4885,7 @@ DOCUMENT(R"(For a shader stage mask that only covers one shader stage, return th
 
 .. note::
   If the shader stage mask covers multiple stages, only the first matching stage will be returned.
-  If the mask is empty, :data:`ShaderStage.Count` will be returned.
+  If the mask is empty, :data:`ShaderStage.Invalid` will be returned.
 
 :param ShaderStageMask stageMask: The shader stage mask.
 :return: The first shader stage covered by the mask.
@@ -4896,7 +4901,7 @@ constexpr inline ShaderStage FirstStageForMask(ShaderStageMask stageMask)
          : (stageMask & ShaderStageMask::Compute)  ? ShaderStage::Compute
          : (stageMask & ShaderStageMask::Task)     ? ShaderStage::Task
          : (stageMask & ShaderStageMask::Mesh)     ? ShaderStage::Mesh
-                                                   : ShaderStage::Count;
+                                                   : ShaderStage::Invalid;
 }
 
 DOCUMENT(R"(A set of flags for events that may occur while debugging a shader

renderdoc/api/replay/shader_types.h

@@ -659,7 +659,7 @@ Maps the contents of a high-level source variable to one or more shader variable
 A single high-level variable may be represented by multiple mappings but only along regular
 boundaries, typically whole vectors. For example an array may have each element in a different
 mapping, or a matrix may have a mapping per row. The properties such as :data:`rows` and
-:data:`elements` reflect the *parent* object.
+:data:`columns` reflect the *parent* object.
 
 .. note::
 

renderdoc/api/replay/structured_data.h

@@ -1501,7 +1501,7 @@ DOCUMENT(R"(Make a structured object as an enum value.
 
 .. note::
   The enum will be stored just as an integer value, but the string name of the enumeration value can
-  be set with :meth:`SDObject.SetCustomString` if desired.
+  be set by changing the string data member if desired.
 
 :param str name: The name of the object.
 :param int val: The integer value of the enum itself.

renderdoc/api/replay/vk_pipestate.h

@@ -928,7 +928,7 @@ to ``0.0`` to ``1.0``.
   DOCUMENT(R"(The extra size in pixels to increase primitives by during conservative rasterization,
 in the x and y directions in screen space.
 
-See :data:`conservativeRasterizationMode`
+See :data:`conservativeRasterization`
 
 :type: float
 )");