Docs overhaul: README, ARCHITECTURE, CONTRIBUTING, install docs - #153
Open
mmelnich wants to merge 5 commits into
Open
Docs overhaul: README, ARCHITECTURE, CONTRIBUTING, install docs#153mmelnich wants to merge 5 commits into
mmelnich wants to merge 5 commits into
Conversation
README gains the banner artwork, a quickstart (clone + install.sh + ctest smoke test), and a driver table with one-line problem statements and paper references, while keeping the pitch, Discord invite, and related-libraries sections. ARCHITECTURE.md is the new project map: a one-paragraph orientation, a mermaid diagram of the layer structure (drivers over computational routines over RandBLAS/BLAS++/LAPACK++ over the BLAS provider), the directory tree with what lives where, the three-tier build explained, and the conventions that hold everywhere. CONTRIBUTING.md collects the development workflow in one place: setup and test loop, review conventions, the experiment-branch naming scheme that used to live in the README (recovered from history), the USE_CUDA two-consumer gotcha, and PR expectations; it points to devnotes/idioms.md for the C++ idiom catalog.
…EADME
INSTALL.md: point at the autoinstaller up front; drop the reference to
the obsolete CQRRP_blocked ICPX issue; fix the consumer snippet that
required CMake 3.0 (current CMake refuses anything below 3.5); remove
the -DCMAKE_BINARY_DIR flag from every recipe (not a real CMake
variable; it never did anything); replace dead bitbucket source links
with the GitHub repositories; de-personalize the MKL tips (machine-
local paths and names replaced with placeholders); document
RandLAPACK_BUILD_TESTS, BUILD_SHARED_LIBS, and SANITIZE_ADDRESS.
INSTALL_SCRIPT.md: rewritten against what install.sh actually does.
The directory diagram now shows the real layout (dependencies install
under install/, not lib/; per-project build directories; install.log);
the step list matches the script's numbered steps including dependency
discovery and reuse; the hardcoded test-count snapshot ('456 tests, 1
fails') that normalized failing tests is gone; key file locations are
corrected (header-only: no library archive; CMake config under the
install prefix); the recompile section explains why make install is
required for downstream consumers; benchmark instructions move to
benchmark/README.md, which also documents building the benchmarks as a
standalone project against an existing install.
…shown, CUDA table expanded The architecture diagram drew the GPU code as a satellite outside the RandLAPACK box; gpu_functions/ and drivers/*_gpu are part of the library, so they now sit inside the subgraph, with cuBLAS/cuSOLVER as their external dependency. extras/ and benchmark/ were missing entirely; they appear as what they are, downstream consumers of the installed RandLAPACK alongside user code. The CUDA/GCC matrix gains the verified CUDA 13.3 + GCC 15.2 configuration and the GCC-14 cap of CUDA 12.9's nvcc, and now states it lists verified configurations rather than exhaustive support.
…om benchmarks Root-level documentation was accumulating (README, INSTALL, INSTALL_SCRIPT, ARCHITECTURE, CONTRIBUTING). The root now keeps only the two files GitHub treats specially, README.md and CONTRIBUTING.md; INSTALL.md, INSTALL_SCRIPT.md, and ARCHITECTURE.md move to docs/, and every reference (README, CONTRIBUTING, install.sh, the CMake gate messages, cross-links) follows. The README closes with a where-to-go table so a reader picks one document by intent instead of surveying the root. extras/README.md now states what the folder is: a holding area for functionality that needs third-party libraries (Eigen, fast_matrix_market) that core RandLAPACK will not depend on, with the graduation policy spelled out (in-house the dependency away and move into RandLAPACK proper, or remain a permanent optional integration); nothing in extras/ is RandLAPACK API. benchmark/README.md and ARCHITECTURE.md state the distinction from the other side: benchmark/ measures performance, extras/ extends functionality.
512px render of the project logo, for use as the organization/repo avatar and anywhere else a square mark is needed. The banner in the README comes from the same artwork set.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
README: banner, quickstart, driver table with paper references. New ARCHITECTURE.md (layer diagram, directory map, three-tier build, conventions) and CONTRIBUTING.md (workflow, review conventions, experiment-branch scheme recovered from the old README, PR expectations). INSTALL.md de-staled: obsolete issue reference, CMake-3.0 consumer snippet, bogus -DCMAKE_BINARY_DIR in every recipe, dead bitbucket links, personal machine paths, undocumented CMake options. INSTALL_SCRIPT.md rewritten against what install.sh actually does (correct layout, discovery documented, hardcoded test-count snapshot removed, header-only noted, make-install-for-downstream explained); benchmark run instructions moved to a new benchmark/README.md. Note: #129 carries a pre-#146 README copy and will pick this up in its rebase.