Add runblock examples to most public methods, fix bugs it surfaced

[petercorke]

Summary

Public methods with a .. runblock:: pycon example: 21% -> 90% (13/62 -> 56/62). The remaining 6 are deliberate exclusions: remove(), Edge.vertices(), BaseVertex.adjacent() are deprecated and not worth featuring with a worked example; showgraph() genuinely opens a browser window via webbrowser.open(), so actually executing it on every doc build is a non-starter.

Adds matplotlib.sphinxext.plot_directive to the docs toolchain: plot()/highlight_path()/highlight_edge()/highlight_vertex() now get both a .. runblock:: (text I/O) and a .. plot:: (a real embedded image, verified generating actual PNGs during the build), matching the convention used elsewhere in the ecosystem.

Two real bugs found and fixed while writing these examples, each verified empirically:

• dotfile() closed sys.stdout when called with the default filename=None (the documented "print to console" behaviour) -- if filename is None or isinstance(filename, str): f.close() closed sys.stdout itself in the None case, since f is sys.stdout there. Any subsequent output in that process then crashed with ValueError: I/O operation on closed file. Reproduced with three lines outside of Sphinx entirely. Fixed to only close a file this method actually opened itself (the str case).
• highlight_vertex()'s docstring documented its parameter as edge/Edge subclass when the real parameter is named vertex. Fixed, and documented the previously-undocumented alpha parameter on both highlight_edge() and highlight_vertex().

Also root-caused a sphinx_autodoc_typehints quirk that was silently corrupting the doc build's reST structure for those same two methods: a method that returns None, has a documented :param:/:type: field list, and has a runblock afterward but no explicit :rtype:, gets an auto-injected return-type annotation that collides with the runblock directive boundary ("Explicit markup ends without a blank line"). Fixed by documenting :rtype: None explicitly wherever this pattern occurs, rather than relying on the auto-injection.

Test plan

• 44/44 tests pass
• Sphinx docs build cleanly -- no RUNBLOCK-ERROR, no Explicit markup warnings, no new warning categories vs. the pre-existing baseline
• .. plot:: blocks confirmed generating real PNG images during the build
• Both bugs reproduced and fixed independently of Sphinx (plain Python repro)

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 85.20%. Comparing base (6c24cfe) to head (98ba77b).

Additional details and impacted files

@@           Coverage Diff           @@
##             main      #11   +/-   ##
=======================================
  Coverage   85.20%   85.20%           
=======================================
  Files           2        2           
  Lines         750      750           
=======================================
  Hits          639      639           
  Misses        111      111           

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.