Skip to content

DOC: Documentation update overhaul Part 1 of many#28

Merged
ilayn merged 41 commits into
mainfrom
moad
Jul 19, 2026
Merged

DOC: Documentation update overhaul Part 1 of many#28
ilayn merged 41 commits into
mainfrom
moad

Conversation

@ilayn

@ilayn ilayn commented Jul 19, 2026

Copy link
Copy Markdown
Owner

One of the downsides of running with LLM is that it slowly drifts and anything that is not test covered is missed. Hence the resulting PRs. It's not nothing, the gist of the docs is there. But the quality level is tripping.

Certain fields were missed and inline code markings were not working; backticks were not recognized. Now, a crude pass will be done with best effort backticking and obvious bugs will be fixed. And LAPACK docs are also choke full of bugs and inconsistencies (not complaining, I'm grateful nevertheless for the attention and care). There are always certain things are missed but the number of functions are simply just too high. So it will be a marathon and not a race.

Regarding doxygen, @verbatim blocks don't remove the comment characters and then dedent properly (that's why it looks the way it looks on official LAPACK docs on Netlib). And it does not understand the markdown triple backtick machinery with @code{...}. So I used a @rst escape and then ...code-block.

Hopefully, this PR will settle the documentation machinery such that further changes will be docstring only. Once this is done, I can make a proper release.

Additional changes included

  • By reusing the left-nav bar as an "asset" and reusing it, instead of regenerating and baking it into the every page over and over again, write phase of Sphinx time cost became negligible. This made the CI job go down from 7 minutes to 15ish seconds (slow 👏).
  • It turns out that Doxygen was generating a very bulky XML per function which was only to be ignored by then Breathe and Sphinx. There is still a very massive read cost coming from Breathe (somehow it is doing a quadratic cost operation for reasons beyond me). It is possible to cut it out and achieve 5x improvement but that means fiddling with Breathe and the result is not like as if it becomes lightning fast. Instead it becomes merely more bearable because Sphinx is also quite slow for this type of lots-of-functions use cases (locally it went down to 30s from 186 s; slow 👏 ). Those rust tools elsewhere are insanely fast for this type of workflows but I currently don't have any appetite for yet another innovative tool. Breathe was apparently struggling with maintenance efforts so maybe soon this will be needed.
  • The left nav bar was always open with all its drawers. Now only the relevant ones are open so it does not annoy the user when the relevant path is below the page.
  • Also integrated the fix DLASQ3, SLASQ3: stop modifying QMAX Reference-LAPACK/lapack#1307 and semicolon's own bug regarding lasq2/lasq3
  • LAPACK docs also have some invalid URLs and non-canonical DOI's from ACM (especially in XXXX_2stage functions). They are all regularized.

@ilayn ilayn added the documentation Improvements or additions to documentation label Jul 19, 2026
@ilayn

ilayn commented Jul 19, 2026

Copy link
Copy Markdown
Owner Author

17 m 35s -> 13m 5s (Adagio 👏)

@ilayn
ilayn merged commit 2f298be into main Jul 19, 2026
9 checks passed
@ilayn
ilayn deleted the moad branch July 19, 2026 12:55
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant