[Doc] let's see if moving the figures out of the tables solves the PDF issue

docs/conf.py

@@ -98,6 +98,7 @@ pygments_style = 'sphinx'
 # If true, keep warnings as "system message" paragraphs in the built documents.
 #keep_warnings = False
 
+numfig = True
 
 # -- Options for HTML output ---------------------------------------------------
 

docs/features/custom_controls.rst

@@ -80,13 +80,15 @@ a GCODE script including user input.
              step: 1
 
 Adding this to ``config.yaml``, restarting the OctoPrint server and switching to the "Control" tab within its
-interface yields the following visual representation:
+interface yields the visual representation in :numref:`fig-configuration-customcontrols-example`.
 
-.. _fig-configuration-custom_controls-example:
+.. _fig-configuration-customcontrols-example:
 .. figure:: ../images/features-custom_controls-example.png
    :align: center
    :alt: The rendered output created through the example configuration
 
+   The rendered output created through the example configuration
+
 As you can see you have two basic types of control definitions here: controls that actually do something (providing a
 button that sends one or more commands to the printer when clicked, displaying output received from the printer) and
 controls that just serve as *container* for other controls, the latter being identified by having a ``children``
@@ -209,12 +211,14 @@ Controls
    * - ``confirm``
      - (Optional) A text to display to the user to confirm his button press. Can be used with sensitive custom controls
        like changing EEPROM values in order to prevent accidental clicks. The text will be displayed in a confirmation
-       dialog like the following:
+       dialog like in :numref:`fig-configuration-customcontrols-confirm`.
 
-       .. _fig-configuration-custom_controls-confirm:
-       .. figure:: ../images/features-custom_controls-confirm.png
-          :align: center
-          :alt: An example confirmation dialog
+.. _fig-configuration-customcontrols-confirm:
+.. figure:: ../images/features-custom_controls-confirm.png
+   :align: center
+   :alt: An example confirmation dialog
+
+   An example confirmation dialog
 
 .. _sec-features-custom_controls-examples:
 
@@ -227,6 +231,8 @@ Parameterized GCODE Script
 ..........................
 
 .. code-block-ext:: yaml
+   :caption: Control definition in ~/.octoprint/config.yaml
+   :name: code-features-custom_controls-example-gcode_script-config_yaml
 
    name: Dance
    script: custom/dance.gco
@@ -240,6 +246,8 @@ Parameterized GCODE Script
        step: 1
 
 .. code-block-ext:: jinja
+   :caption: ~/.octoprint/scripts/gcode/custom/dance.gco
+   :name: code-features-custom_controls-example-gcode_script-dance_gco
 
    {% set center_x = printer_profile.volume.width / 2 %}
    {% set center_y = printer_profile.volume.depth / 2 %}

docs/plugins/concepts.rst

@@ -140,6 +140,8 @@ property instead, manually instantiate your implementation instance and then add
 .. onlineinclude:: https://raw.githubusercontent.com/OctoPrint/Plugin-Examples/master/custom_action_command.py
    :linenos:
    :tab-width: 4
+   :caption: `custom_action_command.py <https://github.com/OctoPrint/Plugin-Examples/blob/master/custom_action_command.py>`_
+   :name: sec-plugin-concepts-hooks-example
 
 .. seealso::
 

docs/plugins/gettingstarted.rst

@@ -260,8 +260,7 @@ Our plugin's directory structure should now look like this::
 
 Restart OctoPrint and open the web interface in your browser (make sure to clear your browser's cache!).
 
-.. _fig-plugins-gettingstarted-helloworld_navbar:
-.. figure:: ../images/plugins_gettingstarted_helloworld_navbar.png
+.. image:: ../images/plugins_gettingstarted_helloworld_navbar.png
    :align: center
    :alt: Our "Hello World" navigation bar element in action
 
@@ -458,8 +457,7 @@ Restart OctoPrint and shift-reload your browser. Your link in the navigation bar
 defined in ``config.yaml`` earlier. Open the "Settings" and click on the new "Hello World" entry that shows up under
 "Plugins".
 
-.. _fig-plugins-gettingstarted-helloworld_settings:
-.. figure:: ../images/plugins_gettingstarted_helloworld_settings.png
+.. image:: ../images/plugins_gettingstarted_helloworld_settings.png
    :align: center
    :alt: Our "Hello World" navigation bar element in action
 
@@ -623,8 +621,7 @@ which we bound to the click event of the "Go" button in our template.
 Restart OctoPrint and shift-reload the browser. You should see a shiny new "Hello World" tab right at the end of the
 tab bar. Click on it!
 
-.. _fig-plugins-gettingstarted-helloworld_tab:
-.. figure:: ../images/plugins_gettingstarted_helloworld_tab.png
+.. image:: ../images/plugins_gettingstarted_helloworld_tab.png
    :align: center
    :alt: Our "Hello World" tab in action
 

docs/plugins/hooks.rst

@@ -24,6 +24,7 @@ octoprint.comm.protocol.action
    .. onlineinclude:: https://raw.githubusercontent.com/OctoPrint/Plugin-Examples/master/custom_action_command.py
       :linenos:
       :tab-width: 4
+      :caption: `custom_action_command.py <https://github.com/OctoPrint/Plugin-Examples/blob/master/custom_action_command.py>`_
 
    :param object comm_instance: The :class:`~octoprint.util.comm.MachineCom` instance which triggered the hook.
    :param str line: The complete line as received from the printer, format ``// action:<command>``
@@ -67,6 +68,7 @@ octoprint.comm.protocol.gcode
    .. onlineinclude:: https://raw.githubusercontent.com/OctoPrint/Plugin-Examples/master/rewrite_m107.py
       :linenos:
       :tab-width: 4
+      :caption: `rewrite_m107.py <https://github.com/OctoPrint/Plugin-Examples/blob/master/rewrite_m107.py>`_
 
    :param object comm_instance: The :class:`~octoprint.util.comm.MachineCom` instance which triggered the hook.
    :param str cmd: The GCODE command for which the hook was triggered. This is the full command as taken either
@@ -103,6 +105,7 @@ octoprint.comm.protocol.scripts
    .. onlineinclude:: https://raw.githubusercontent.com/OctoPrint/Plugin-Examples/master/message_on_connect.py
       :linenos:
       :tab-width: 4
+      :caption: `message_on_connect.py <https://github.com/OctoPrint/Plugin-Examples/blob/master/message_on_connect.py>`_
 
    :param MachineCom comm_instance: The :class:`~octoprint.util.comm.MachineCom` instance which triggered the hook.
    :param str script_type: The type of the script for which the hook was called, currently only "gcode" is supported here.

src/octoprint/plugin/types.py

@@ -250,6 +250,8 @@ class TemplatePlugin(OctoPrintPlugin):
 		      :align: center
 		      :alt: Structure of navbar plugins
 
+		      Structure of navbar plugins
+
 		   Configures a navbar component to inject. The following keys are supported:
 
 		   .. list-table::
@@ -286,6 +288,8 @@ class TemplatePlugin(OctoPrintPlugin):
 		      :align: center
 		      :alt: Structure of sidebar plugins
 
+		      Structure of sidebar plugins
+
 		   Configures a sidebar component to inject. The following keys are supported:
 
 		   .. list-table::
@@ -338,6 +342,8 @@ class TemplatePlugin(OctoPrintPlugin):
 		      :align: center
 		      :alt: Structure of tab plugins
 
+		      Structure of tab plugins
+
 		   Configures a tab component to inject. The value must be a dictionary, supported values are the following:
 
 		   .. list-table::
@@ -385,6 +391,8 @@ class TemplatePlugin(OctoPrintPlugin):
 		      :align: center
 		      :alt: Structure of settings plugins
 
+		      Structure of settings plugins
+
 		   Configures a settings component to inject. The value must be a dictionary, supported values are the following:
 
 		   .. list-table::