[doc] Fix description list handling for pydrake (#18006)

Handle dl/dt/dd tags in the pydrake doc toolchain by translating them
into bold titles and stripping the rest. This fixes a visual bug in the
pydrake.visualization docs.

Also fix a grammar error that was irking me and clarify that --quick
in the doc build instructions only works for Doxygen.

bindings/pydrake/systems/drawing_graphviz_example.py

@@ -21,7 +21,7 @@
 from pydrake.systems.framework import DiagramBuilder
 from pydrake.visualization import AddDefaultVisualization
 
-# If running under `bazel run`, output to cwd to the user can find it.
+# If running under `bazel run`, output to cwd so the user can find it.
 # If running under `bazel test` avoid polluting the test's cwd.
 for env_name in ['BUILD_WORKING_DIRECTORY', 'TEST_TMPDIR']:
     if env_name in os.environ:

doc/_pages/documentation_instructions.md

@@ -47,7 +47,7 @@ $ bazel run //doc/doxygen_cxx:build -- --serve drake.math            # C++ math
 $ bazel run //doc/pydrake:build     -- --serve pydrake.math          # Python math API.
 $ bazel run //doc:build             -- --serve {drake,pydrake}.math  # Both at once.
 
-# Further speed up preview by omitting expensive `dot` graphs:
+# Further speed up preview by omitting expensive `dot` graphs (C++ API only):
 $ bazel run //doc/doxygen_cxx:build -- --serve --quick drake.math
 ````
 

tools/workspace/pybind11/mkdoc_comment.py

@@ -157,6 +157,10 @@ def replace_html_tags(s):
     s = re.sub(r'</?ul>', r'', s, flags=re.IGNORECASE)
     s = re.sub(r'</li>', r'\n\n', s, flags=re.IGNORECASE)
 
+    s = re.sub(r'</?dl>', r'', s, flags=re.IGNORECASE)
+    s = re.sub(r'<dt>(.*?)</dt>', r'\n**\1**\n', s, flags=re.IGNORECASE)
+    s = re.sub(r'</?dd>', r'', s, flags=re.IGNORECASE)
+
     s = re.sub(r'<a href="([\w:.?/#]+)">(.*?)</a>', r'`\2 <\1>`_', s,
                flags=re.DOTALL | re.IGNORECASE)