Merge pull request #4774 from rgommers/improve-docs

Improve documention content, formatting, and html theme

Author: martin-frbg

docs/about.md

@@ -2,25 +2,45 @@
 
 We have a [GitHub discussions](https://github.com/OpenMathLib/OpenBLAS/discussions/) forum to discuss usage and development of OpenBLAS. We also have a [Google group for *users*](https://groups.google.com/forum/#!forum/openblas-users) and a [Google group for *development of*](https://groups.google.com/forum/#!forum/openblas-dev) OpenBLAS. 
 
-## Donations
-
-You can read OpenBLAS statement of receipts and disbursement and cash balance on [google doc](https://docs.google.com/spreadsheet/ccc?key=0AghkTjXe2lDndE1UZml0dGpaUzJmZGhvenBZd1F2R1E&usp=sharing). A backer list is available [on GitHub](https://github.com/OpenMathLib/OpenBLAS/blob/develop/BACKERS.md).
-
-We welcome the hardware donation, including the latest CPU and boards.
-
 ## Acknowledgements
 
-This work is partially supported by
+This work was or is partially supported by the following grants, contracts and institutions:
+
 * Research and Development of Compiler System and Toolchain for Domestic CPU, National S&T Major Projects: Core Electronic Devices, High-end General Chips and Fundamental Software (No.2009ZX01036-001-002)
 * National High-tech R&D Program of China (Grant No.2012AA010903)
+* [PerfXLab](http://www.perfxlab.com/)
+* Chan Zuckerberg Initiative's Essential Open Source Software for Science program:
+    * Cycle 1 grant: [Strengthening NumPy's foundations - growing beyond code](https://figshare.com/articles/journal_contribution/Proposal_NumPy_OpenBLAS_for_Chan_Zuckerberg_Initiative_EOSS_2019_round_1/10302167) (2019-2020)
+    * Cycle 3 grant: [Improving usability and sustainability for NumPy and OpenBLAS](https://chanzuckerberg.com/eoss/proposals/improving-usability-and-sustainability-for-numpy-and-openblas/) (2020-2021)
+* Sovereign Tech Fund funding: [Keeping high performance linear algebra computation accessible and open for all](https://www.sovereigntechfund.de/tech/openblas) (2023-2024)
+
+Over the course of OpenBLAS development, a number of donations were received.
+You can read OpenBLAS's statement of receipts and disbursement and cash balance in
+[this Google doc](https://docs.google.com/spreadsheet/ccc?key=0AghkTjXe2lDndE1UZml0dGpaUzJmZGhvenBZd1F2R1E&usp=sharing) (covers 2013-2016).
+A list of backers is available [in BACKERS.md](https://github.com/OpenMathLib/OpenBLAS/blob/develop/BACKERS.md) in the main repo.
+
+### Donations
+
+We welcome hardware donations, including the latest CPUs and motherboards.
+
+
+## Open source users of OpenBLAS
+
+Prominent open source users of OpenBLAS include:
+
+* [Julia](https://julialang.org) - a high-level, high-performance dynamic programming language for technical computing
+* [NumPy](https://numpy.org) - the fundamental package for scientific computing with Python
+* [SciPy](https://scipy.org) - fundamental algorithms for scientific computing in Python
+* [R](https://www.r-project.org/) - a free software environment for statistical computing and graphics
+* [OpenCV](https://opencv.org/) - the world's biggest computer vision library
 
-## Users of OpenBLAS
+OpenBLAS is packaged in most major Linux distros, as well as general and
+numerical computing-focused packaging ecosystems like Nix, Homebrew, Spack and
+conda-forge.
 
-* <a href='http://julialang.org/'>Julia - a high-level, high-performance dynamic programming language for technical computing</a><br />
-* Ceemple v1.0.3 (C++ technical computing environment), including OpenBLAS, Qt, Boost, OpenCV and others. The only solution with immediate-recompilation of C++ code. Available from <a href='http://www.ceemple.com'>Ceemple C++ Technical Computing</a>.
-* [netlib-java](https://github.com/fommil/netlib-java) and various upstream libraries, allowing OpenBLAS to be used from languages on the Java Virtual Machine.
+OpenBLAS is used directly by libraries written in C, C++ and Fortran (and
+probably other languages), and directly by end users in those languages.
 
-<!-- TODO: academia users, industry users, hpc centers deployed openblas, etc. -->
 
 ## Publications
 

docs/build_system.md

@@ -1,3 +1,8 @@
+This page describes the Make-based build, which is the default/authoritative
+build method. Note that the OpenBLAS repository also supports building with
+CMake (not described here) - that generally works and is tested, however there
+may be small differences between the Make and CMake builds.
+
 !!! warning
     This page is made by someone who is not the developer and should not be considered as an official documentation of the build system. For getting the full picture, it is best to read the Makefiles and understand them yourself.
 
@@ -95,10 +100,21 @@ NUM_PARALLEL    - define this to the number of OpenMP instances that your code m
 ```
 
 
-OpenBLAS uses a fixed set of memory buffers internally, used for communicating and compiling partial results from individual threads.
-For efficiency, the management array structure for these buffers is sized at build time - this makes it necessary to know in advance how
-many threads need to be supported on the target system(s). 
-With OpenMP, there is an additional level of complexity as there may be calls originating from a parallel region in the calling program. If OpenBLAS gets called from a single parallel region, it runs single-threaded automatically to avoid overloading the system by fanning out its own set of threads. 
-In the case that an OpenMP program makes multiple calls from independent regions or instances in parallel, this default serialization is not
-sufficient as the additional caller(s) would compete for the original set of buffers already in use by the first call.
-So if multiple OpenMP runtimes call into OpenBLAS at the same time, then only one of them will be able to make progress while all the rest of them spin-wait for the one available buffer. Setting NUM_PARALLEL to the upper bound on the number of OpenMP runtimes that you can have in a process ensures that there are a sufficient number of buffer sets available
+OpenBLAS uses a fixed set of memory buffers internally, used for communicating
+and compiling partial results from individual threads. For efficiency, the
+management array structure for these buffers is sized at build time - this
+makes it necessary to know in advance how many threads need to be supported on
+the target system(s).
+
+With OpenMP, there is an additional level of complexity as there may be calls
+originating from a parallel region in the calling program. If OpenBLAS gets
+called from a single parallel region, it runs single-threaded automatically to
+avoid overloading the system by fanning out its own set of threads. In the case
+that an OpenMP program makes multiple calls from independent regions or
+instances in parallel, this default serialization is not sufficient as the
+additional caller(s) would compete for the original set of buffers already in
+use by the first call. So if multiple OpenMP runtimes call into OpenBLAS at the
+same time, then only one of them will be able to make progress while all the
+rest of them spin-wait for the one available buffer. Setting `NUM_PARALLEL` to
+the upper bound on the number of OpenMP runtimes that you can have in a process
+ensures that there are a sufficient number of buffer sets available.