Add pci-sim developer guide

The pci-sim module now has several focused contributor pages, but it lacks a
single maintainer-oriented guide that explains how the out-of-tree kernel
module works and how to safely extend it. That makes it difficult for Cyborg
contributors who understand OpenStack and virtualization to reason about the
PCI, SR-IOV, IOMMU, VFIO, and TTY kernel interfaces used by the module.

Add a long-form pci-sim developer guide covering the module's design goals,
core kernel concepts, build flow, source layout, data paths, extension
workflows, validation strategy, troubleshooting, and limitations. Link the new
page from the pci-sim contributor index.

Also align the Sphinx tox commands with Nova's stricter docs pattern by using
--keep-going and parallel builds for docs, PDF docs, release notes, and the API
reference. This keeps warnings fatal while allowing Sphinx to report more than
the first issue.

Generated-By: pi gpt-5.5
Change-Id: Iba69ec4f17b62b502ca9d83cf2191dc0152200a3
Signed-off-by: Sean Mooney <work@seanmooney.info>

doc/source/contributor/pci-sim/index.rst

@@ -6,7 +6,7 @@ pci-sim
 
 ``pci-sim`` provides an out-of-tree build of the ``fake_pci_sriov`` Linux
 kernel module for DevStack and CI testing of SR-IOV PCI passthrough flows
-without physical SR-IOV hardware.  It is included in the Cyborg repository
+without physical SR-IOV hardware. It is included in the Cyborg repository
 under the top-level ``pci-sim/`` directory and is built and loaded
 automatically by the Cyborg DevStack plugin.
 
@@ -14,6 +14,7 @@ automatically by the Cyborg DevStack plugin.
    :maxdepth: 2
 
    overview
+   developer-guide
    build
    devstack
    testing

tox.ini

@@ -73,8 +73,8 @@ deps =
   -c{env:TOX_CONSTRAINTS_FILE:https://releases.openstack.org/constraints/upper/master}
   -r{toxinidir}/doc/requirements.txt
 commands =
-    rm -rf doc/build/html
-    sphinx-build -W -b html doc/source doc/build/html
+    rm -rf doc/build/html doc/build/doctrees
+    sphinx-build -W --keep-going -b html -j auto doc/source doc/build/html
 
 [testenv:pdf-docs]
 description =
@@ -82,14 +82,16 @@ description =
 deps = {[testenv:docs]deps}
 commands =
   rm -rf doc/build/pdf
-  sphinx-build -W -b latex doc/source doc/build/pdf
+  sphinx-build -W --keep-going -b latex -j auto doc/source doc/build/pdf
   make -C doc/build/pdf
 
 [testenv:releasenotes]
 description =
   Generate release notes.
 deps = {[testenv:docs]deps}
-commands = sphinx-build -a -W -E -d releasenotes/build/doctrees -b html releasenotes/source releasenotes/build/html
+commands =
+  rm -rf releasenotes/build
+  sphinx-build -W --keep-going -b html -j auto releasenotes/source releasenotes/build/html
 
 [testenv:debug]
 commands = oslo_debug_helper -t cyborg/tests {posargs}
@@ -102,7 +104,7 @@ description =
 deps = {[testenv:docs]deps}
 commands =
   rm -rf api-ref/build
-  sphinx-build -W -b html -d api-ref/build/doctrees api-ref/source api-ref/build/html
+  sphinx-build -W --keep-going -b html -j auto api-ref/source api-ref/build/html
 allowlist_externals = rm
 
 [flake8]