docs: versioned PDF user guide built from the Sphinx sources

[bodono]

Draft for discussion, following #474: a user's guide as a single versioned PDF, generated from the same Sphinx sources as the site so it cannot drift from it.

• make guide in docs/src renders a curated subset of the docs through Sphinx's LaTeX builder into _build/latex/scs_user_guide.pdf, running pdflatex directly so the only extra requirement is a TeX installation. The release number from conf.py appears on the title page, which is what versions the guide.
• The PDF has its own master document, guide/index.rst, which selects what it contains: C and Python install and API, cones, matrices, settings, info, exit flags, compile flags, linear solvers, BLAS/LAPACK, best practices, help, the algorithm as background, and citing. It points to the site for the other language interfaces and the worked examples. 62 pages.
• The docs workflow installs TeX and publishes the PDF next to the site as scs_user_guide.pdf; the front page links to it and says to cite the published papers rather than the guide.
• The root toctree is reordered into guide order (install and use first, the algorithm as background), which changes the site's navigation order too.
• guide/best_practices.rst is a new draft chapter (scaling, tolerances, workspace reuse, backend choice, acceleration, reading the log, certificates, differentiating through SCS, when to use something else). It is written for maintainer review and every recommendation in it should be checked.
• Layout for print: the cone, settings, compile-flag and info tables get explicit column widths, the settings and compile-flag tables become page-breaking longtables, tables are set a size down in the PDF, the vertical spacing around C API entries is tightened, and ScsCone, ScsSettings and ScsInfo are shown in outline form with a pointer to the table that documents each field.
• Algorithm pages audited against src/scs.c and include/glbopts.h: the embedding (u, Q, C_+) is now defined on the algorithm page; root_plus is written in terms of the cached g = (R + M)^{-1}(c, -b) and per-iteration p rather than an undefined r; the adaptive-scale band is [1/10, 10] on the geometric-mean ratio, not [1/3, 3]; and a sign typo in the unequilibrated primal residual is fixed. Every quoted default was checked.
• Two source fixes the LaTeX build needed: the JavaScript example's .. math:: blocks carry their own align*, which LaTeX rejects inside Sphinx's split wrapper, so they are marked :nowrap: (no change to the HTML rendering); and a few Unicode math symbols that reach the PDF through code comments are declared in the preamble.

Built locally: Sphinx -W clean for both the HTML and LaTeX builders.

🤖 Generated with Claude Code