[llvm] [Offload] Expand documentation with & build guide (PR #149792)

[via llvm-commits]

llvmbot wrote:


<!--LLVM PR SUMMARY COMMENT-->

@llvm/pr-subscribers-offload

Author: Kenneth Benzie (Benie) (kbenzie)

<details>
<summary>Changes</summary>

This patch introduces essential information to the landing page of the Sphinx documentation:

* Copy and translate the contents of `offload/README.md` as the project summary section
* Document how to configure CMake and build the project
* Document running tests
* Document building the Sphinx documentation


---
Full diff: https://github.com/llvm/llvm-project/pull/149792.diff


1 Files Affected:

- (modified) offload/docs/index.rst (+97) 


``````````diff
diff --git a/offload/docs/index.rst b/offload/docs/index.rst
index 481d1f7ddd8b8..3de16776f0903 100644
--- a/offload/docs/index.rst
+++ b/offload/docs/index.rst
@@ -6,12 +6,109 @@
 Welcome to Offload's documentation!
 ===================================
 
+Summary
+-------
+
+The Offload subproject aims at providing tooling, runtimes, and APIs that allow
+users to execute code on accelerators or other "co-processors" that may or may
+not match the architecture of their "host". In the long run, all kinds of
+targets are in scope of this effort, including but not limited to: CPUs, GPUs,
+FPGAs, AI/ML accelerators, distributed resources, etc.
+
+For OpenMP offload users, the project is ready and fully usable. The final API
+design is still under development. More content will show up here and on our
+webpage soon. In the meantime, people are encouraged to participate in our
+meetings (see below) and check our `development board
+<https://github.com/orgs/llvm/projects/24/>`_ as well as the discussions on
+`Discourse <https://discourse.llvm.org/tag/offload>`_.
+
 .. toctree::
    :maxdepth: 2
    :caption: Contents:
 
    offload-api
 
+Meetings
+--------
+
+Every second Wednesday, 7:00 - 8:00am PT, starting Jan 24, 2024. Alternates
+with the OpenMP in LLVM meeting. `invite.ics
+<https://drive.google.com/file/d/1AYwKdnM01aV9Gv9k435ArEAhn7PAer7z/view?usp=sharing>`_
+`Meeting Minutes and Agenda
+<https://docs.google.com/document/d/1PAeEshxHCv22JDBCPA9GXGggLp0t7rsnD_jL04MBbzw/edit?usp=sharing>`_.
+
+
+Building
+--------
+
+A minimal Linux build CMake configuration:
+
+.. code-block:: console
+
+  $ cmake llvm -Bbuild \
+      -DCMAKE_BUILD_TYPE=Release \
+      -DLLVM_ENABLE_PROJECTS='clang;clang-tools-extra;lldb;lld' \
+      -DLLVM_ENABLE_RUNTIMES='offload;openmp' \
+      -DLLVM_BINUTILS_INCDIR=/usr/include \
+      -DLLVM_INSTALL_GTEST=ON
+  $ cmake --build build
+
+* ``LLVM_ENABLE_RUNTIMES`` must include ``openmp`` as it is currently a
+  dependency of ``offload`` during the initial transitional phase of the
+  project.
+* ``LLVM_BINUTILS_INCDIR`` ensures that ``LLVMgold.so`` build is enabled which
+  is necessary for ``check-offload`` testing.
+* ``LLVM_INSTALL_GTEST`` ensures that the unit tests can be built which is
+  necessary for ``check-offload-unit`` testing.
+
+.. hint::
+
+  As part of the main build an `ExternalProject
+  <https://cmake.org/cmake/help/latest/module/ExternalProject.html>`_ will be
+  created at ``build/runtimes/runtimes-bins`` which contains the Offload
+  sub-build. Additional build targets are present in the sub-build which are
+  not accessible in the LLVM build.
+
+Running Tests
+^^^^^^^^^^^^^
+
+There are two main check targets:
+
+* ``check-offload`` runs the OpenMP tests, this is available in both the LLVM
+  build as well as the sub-build.
+* ``check-offload-unit`` runs the Offload API unit test, this is only available
+  in the sub-building.
+
+Building Documentation
+^^^^^^^^^^^^^^^^^^^^^^
+
+Additional CMake options are necessary to build the Sphinx documentation.
+Firstly, we need to ensure the Python dependencies are available, ideally using
+a virtual environment:
+
+.. code-block:: console
+
+  $ python -m venv env
+  $ source env/bin/activate
+  $ pip install -r requirements.txt
+
+Assuming we already have an existing build described above, we need to
+reconfigure the Offload sub-build, this will enable the ``doc-offload-html``
+target.
+
+.. code-block:: console
+
+  $ cmake runtimes -Bbuild/runtimes/runtimes-bins \
+      -DLLVM_ENABLE_SPHINX:BOOL=ON
+  $ cmake --build build
+
+Once the documentation is built it can be viewed on `localhost:8000
+<http://localhost:8000>`_ as follows:
+
+.. code-block:: console
+
+  $ cd build/runtimes/runtimes-bins/offload/docs/html
+  $ python -m http.server
 
 Indices and tables
 ==================

``````````

</details>


https://github.com/llvm/llvm-project/pull/149792