OpenBLAS
OpenBLAS copied to clipboard
OpenMathLib
Adding html docs for the project
I'd like to propose and work on adding html documentation for the project. This would make it easier for users - both direct C/Fortran API users and downstream users who experience OpenBLAS's runtime behavior through Python, Julia, R or other such languages - as well as packagers, contributors and other potentially interested folks to find what they are looking for. And it will help when trying to contribute to the docs (right now it's on wiki pages that cannot be edited by external contributors).
This would involve:
- incorporating most of the info now on the wiki,
- updating that wiki info to ensure it's all up-to-date and reads well (in separate PRs or commits, so it's easy to review what was changed)
- adding some new docs where appropriate,
- a CI job to auto-build the docs on PRs and build + deploy them on PR merges
- tweaks to other CI jobs to not run for docs-only PRs
This will require choosing a doc tool and deployment method. I'd propose MkDocs with the Material for MkDocs theme, as that is quite easy to use, well-documented/maintained, and has a nice look-and-feel. And deploying to GitHub Pages. @martin-frbg if you'd prefer another setup (e.g., Docusaurus is good too), then of course I'd be happy to use whatever you would like to see here.
MkDocs looks nice enough (though I'd prefer to not tie this to one particular tool exclusively, which could create a barrier for future contributors. But if all it does is pretty-print markdown, there are probably ways around that).
Another option might be to set up a runner that auto-converts the wiki (which IIRC is just another repo) to html and possibly pdf. This would offer the advantage of having only a single source to update, though I guess the style options may be a bit limited, possibly leading to a less visually pleasing result.
(Sad that we had to lock down the wiki due to repeated vandalism - it felt a lot more friendly when users could just add their build recipes and special use cases directly)
But if all it does is pretty-print markdown,
Pretty much. The docs are written in pure Markdown, so it's about as easy as it gets for working on them. The structure, navbar, etc. are all derived from the titles and subfolders. Here's an example, it's basically one ~75 LoC mkdocs.yml config file and then plain .md files with docs: https://github.com/pypackaging-native/pypackaging-native, turns into this website.
This would offer the advantage of having only a single source to update
I'd suggest that once you're happy with the html docs and see that it's just as easy to update, to retire the wiki pages and replace them with a link to the rendered docs page covering the same topic.
(Sad that we had to lock down the wiki due to repeated vandalism - it felt a lot more friendly when users could just add their build recipes and special use cases directly)
Yeah I've had the same problem in multiple projects:(
What is wrong with source headings in reference lapack? Like they were ok for some 40 years, now need to convert to 30 years old html?
@brada4 there's nothing wrong with those. I did not mean to suggest to add reference API docs for all standard BLAS/LAPACK functions, I agree with you that that's not all that useful (or at least, lots of effort for little gain). Pointing to the relevant headers or html docs like https://netlib.org/blas/#_blas_routines should be just fine.
What I proposed instead was to include the info on building, usage, troubleshooting, contributing, etc. that is now scattered across pages and files like:
- https://github.com/xianyi/OpenBLAS/blob/develop/README.md
- https://github.com/xianyi/OpenBLAS/blob/develop/USAGE.md
- https://github.com/xianyi/OpenBLAS/wiki
- https://github.com/xianyi/OpenBLAS/blob/develop/Makefile
- https://github.com/xianyi/OpenBLAS/blob/develop/Changelog.txt
- etc.
and put them in a single easier to read format that can be searched, linked, contributed to, etc. Some files like Changelog.txt should probably remain unchanged and simply pulled into the docs and rendered. Others may be restructured and improved.
To give a concrete example: say I am a new contributor and want to run the test suite. Neither the contributing section in README.md nor CONTRIBUTORS.md say anything about it. Then manually browsing the wiki, I get to https://github.com/xianyi/OpenBLAS/wiki/Developer-manual#run-openblas-test, which is very short. And then points to https://github.com/xianyi/BLAS-Tester, which hasn't been updated since 2016, so I doubt that that's the way. Centralizing and then updating this info and providing it as html docs seems quite useful to me.
You can dump wiki and convert to more pleasant formats like DOCX if you want. IMO markdown is readable as text while html not so much.
git clone https://github.com/xianyi/openblas.wiki.git
You can dump wiki and convert to more pleasant formats like DOCX if you want. IMO markdown is readable as text while html not so much.
The goal is to keep the sources in Markdown (most readable indeed, and pretty much everyone is familiar with it), the html is autogenerated at build time and never committed. That's how not only MkDocs but pretty much all static site generators work.
Could you please have a look at https://github.com/pypackaging-native/pypackaging-native as an example? It's plain .md files under docs/, nothing else there. And a single 75 LoC mkdocs.yml config file at the top level of the repo plus a 35 LoC CI job at .github/workflows/deploy.yml- that will be everything that's needed.
Then by means of braindead automation link-spammed wiki turns into official distribution having permalinks spamware. "it wasnt me, computer did it"
Um, brada4, what are you on about ? We already locked down the wiki to keep out the link spam, and the idea is to expand on what is currently in the wiki (and strewn around in the discussion on various resolved tickets) and possibly also make some of it available offline as part of distribution packaging. These ideas have been around for a while, Kazushige Goto's notes from the early days of GotoBLAS more than ten years ago are just not sufficient anymore as documentation for the current state and usage patterns of the project.
@rgommers BLAS-Tester - basically the ATLAS testsuite adapted for building with OpenBLAS - is still very much relevant for regression-testing OpenBLAS. It may not have been updated since 2016, but neither has the (reference) BLAS so far.
Maybe some wiki pages (in markdown or plaintext format) could be brought in to displace GotoBLAS documents.Its been a while since anyone cared about kernel 2.4 bugs.