[Offload] Expand documentation with & build guide

[kbenzie]

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

[llvmbot]

@llvm/pr-subscribers-offload

Author: Kenneth Benzie (Benie) (kbenzie)

Changes

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 --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
 ==================

[RossBrunton]

Did we ever update this invite with the timezone change?

[jhuber6]

Very unfortunate dependency that we will hopefully get rid of.

[kbenzie]

I was wonder if this should be made an implicit dependency, at least until we get to a point where we can break the dependency. Thoughts?

[jhuber6]

check-offload should run check-offload-unit as well, someone needs to do that plumbing through lit.

[kbenzie]

I'll have a look at that in a future PR along with making docs-offload-html available in the root LLVM build too.

[kbenzie]

#150230

[jhuber6]

This is just standard stuff, you need to contact someone in the LLVM foundation to begin hosting this documentation so people can actually read it.

[kbenzie]

I've created the Website for LLVM Offload project topic on over on Discourse making the request.

[RossBrunton]

Is it possible for this to be passed in from the "main" LLVM build rather than requiring a janky sub-project configure? Probably makes sense as a separate task.

[kbenzie]

Yeah, I'll look into that in a separate PR alongside making check-offload-unit part of check-offload.