View plugin docs with sasmodels.compare -help

[pkienzle]

Generate an html file from the plugin docstring and view it with a web browser. The same technique can also be used to view .rst files from the doc directory.

This renders with the lightweight docutils reStructuredText interpreter without all the extensions available to sphinx so not everything works perfectly.

Test using:

python -m sasmodels.compare -help ellipsoid
python -m sasmodels.compare doc/guide/orientation.rst

I was able to render every builtin model with only minor difficulties. I found several nitpicks with docstrings, which I fixed in #762. Similarly for most of the .rst files for sasview/sasmodels/sasdata.

Rendering is good enough for rapid debugging of both the reStructuredText markup and the LaTeX markup.

Known issues:

• Sphinx directives (:func: :mod: :class: ...) and roles (:ref: :numref: :eq: ...) are stubbed out.
• No links to the code or the manual
• No figure numbers or equation numbers, or links to figures or equations
• No table of contents or links to other models
• The style sheet was cribbed from the current snapshot from sasview, and it will likely drift. I was not able to use the Sphinx css directly because the tag structure generated by docutils is somewhat different from that generated by sphinx [I should probably have included more of the stylesheet]
  I'm now using the full stylesheet, but it is copied from sphinx so it will still drift from sphinx over time.
• The MathJax sphinx extension adds some processing to the docutils math role such as :nowrap: and :label:. These are automatically stripped before rendering.
• Math which needs :nowrap: will fail because docutils puts it in a surrounding \begin{align*}...\end{align*} environment. The begin and end align environment macros are also stripped before rendering.
• The html files are generated in the same directory as the docs, then immediately deleted (otherwise relative references to the img directory would fail); this may lead to some flakiness in the rendering
• Not tested on Windows or Linux. Only tested on Mac Safari.
• I'm not running genmodel.py, so the automatic plots and links to the source on github are not present in the models.
• Should use intersphinx to resolve links. For example, the cylinder model has a figure reference cylinder_angle_definition which appears in the inventory for the sasmodels docs. If we install the package with the doc/_build/html/objects.inv file then we can resolve the links (and report if the link is broken).

python -m sphinx.ext.intersphinx doc/_build/html/objects.inv
    ...
std:label
    ...
    correlation-length                       correlation_length                      : model/correlation_length.html#correlation-length
    cylinder                                                                         : model/cylinder.html#cylinder
    cylinder-angle-definition                Angles \theta and \phi orient the cylinder relative to the beam line: model/cylinder.html#cylinder-angle-definition
    dab                                                                              : model/dab.html#dab
    ellipsoid                                                                        : model/ellipsoid.html#ellipsoid
    ellipsoid-comparison-2d                  Comparison of the intensity for uniformly distributed ellipsoids: model/ellipsoid.html#ellipsoid-comparison-2d
    ...

• Produce a header/footer using the intersphinx links which looks something like:
  SasView 6.2.0 documentation » SasView User Documentation » Model Functions ... modules | index
  
  I've hard-coded the links to sasview docs in the header and footer. I'm pointing next and previous to the models page as well. I'm not building an index for all the plugins for this PR.

• Change html generator to reproduce the sphinx div structure so we can use the css templates directly. This also gives us a mechanism to inject the headers and footers for the objects inventory.
  
  I've hard-coded the structure for the classic theme. Supporting arbitrary themes will require jinja2 with the sphinx templates and variables.
  
  [Note: This structure is defined by sphinx/themes/basic/layout.html. A general solution to dynamic docs would need to render from the same template used to make the css. That way our generated docs would always follow the same theme.]

TODO

• The css file will be included in the package (I hope), but it needs to be a file on disk for the browser to see it---this may fail if sasmodels is part of a zip import directory.
• SasView sphinx conf.py should switch to extensions = [..., "sasmodels.sphinx.dollarmath", ...]

[krzywon]

Code seems fine. Functionality not tested.

[codescene-access]

No quality gates enabled for this code.

See analysis details in CodeScene

Quality Gate Profile: Custom Configuration
Install CodeScene MCP: safeguard and uplift AI-generated code. Catch issues early with our IDE extension and CLI tool.