Installation tutorial (#275)

This updates installation prerequisites and how to install from pip in
readme, and updates how to build docs and run gtests.

Signed-off-by: Mark Harris <mharris@nvidia.com>

---------

Signed-off-by: Mark Harris <mharris@nvidia.com>
Signed-off-by: Francis Williams <fwilliams@users.noreply.github.com>
Co-authored-by: Francis Williams <fwilliams@users.noreply.github.com>

Author: harrism

README.md

@@ -21,32 +21,53 @@ Lastly, our [documentation](docs) provides deeper details on the concepts as wel
 
 ## Installing *f*VDB
 
-During the project's initial development stages, it is necessary to [run the build steps](#building-fvdb-from-source) to install ƒVDB. Eventually, ƒVDB will be provided as a pre-built, installable package. We support building the latest ƒVDB version for the following library configurations:
+The `fvdb_core` Python package can be installed either using published packages with pip or built
+from source.
 
-|   PyTorch      | Python      | CUDA |
-| -------------- | ----------- | ------------ |
-|  2.8.0-2.9.0   | 3.10 - 3.13 | 12.8 - 13.0 |
+### Platform Requirements
 
+#### Software
 
+fVDB is currently supported on the matrix of dependencies in the following table.
 
-** Notes:**
-* Linux is the only platform currently supported (Ubuntu >= 22.04 recommended).
-* A CUDA-capable GPU with Ampere architecture or newer (i.e. compute capability >=8.0) is recommended to run the CUDA-accelerated operations in ƒVDB.  A GPU with compute capabililty >=7.0 (Volta architecture) is the minimum requirement but some operations and data types are not supported.
+| OS         | PyTorch     | Python      | CUDA        |
+| ---------- | ----------- | ----------- | ----------- |
+| Linux Only | 2.8.0-2.9.0 | 3.10 - 3.13 | 12.8 - 13.0 |
 
+#### Hardware
+
+A CUDA-capable GPU with Ampere architecture or newer (i.e. compute capability >=8.0) is recommended
+to run the CUDA-accelerated operations in ƒVDB.  A GPU with compute capabililty >=7.0 (Volta) is the
+minimum requirement but some operations and data types are not supported.
+
+### Package Installation with pip
+
+Currently, pip wheels are built with PyTorch 2.8 and CUDA 12.8 only. Versions for Python 3.10-3.13
+are provided.
+
+Install fvdb_core using the following pip command.
+
+```
+pip install fvdb_core==0.3.0+pt28.cu129 --extra-index-url="https://d36m13axqqhiit.cloudfront.net/simple" torch==2.8
+```
 
 ## Building *f*VDB from Source
 
 ### Environment Management
-ƒVDB is a Python library implemented as a C++ PyTorch extension.  Of course you can build ƒVDB in whatever environment suits you, but we provide three distinct paths to constructing reliable environments for building and running ƒVDB. These are separate options and are not intended to be used together.
-
-1. **RECOMMENDED** [conda](#option-1-conda-environment-recommended)
-2. Using [Docker](#option-2-docker-container)
-3. [Python virtual environment](#option-3-python-virtual-environment)
 
-`conda` tends to be more flexible since reconfiguring toolchains and modules to suit your larger project can be dynamic, but at the same time this can be a more brittle experience compared to using a virtualized `docker` container.  Using `conda` is generally recommended for development and testing, while using `docker` is recommended for CI/CD and deployment.
+ƒVDB is a Python library implemented as a C++ Pytorch extension. We provide three paths to
+constructing reliable environments for building and running ƒVDB. These are separate options not
+intended to be used together (however with modification you can of course use, for example, a conda
+or pip environment inside a docker container).
 
----
+1. **RECOMMENDED** [conda](#option-1-setting-up-a-conda-environment-recommended)
+2. Using [docker](#option-2-setting-up-a-docker-container)
+3. Python virtual environment. [venv](#option-3-setting-up-a-python-virtual-environment)
 
+`conda` tends to be more flexible since reconfiguring toolchains and modules to suit your larger
+project can be dynamic, but at the same time this can be a more brittle experience compared to using
+a virtualized `docker` container.  Using `conda` is generally recommended for development and
+testing, while using `docker` is recommended for CI/CD and deployment.
 
 #### **OPTION 1** Conda Environment (Recommended)
 
@@ -148,7 +169,18 @@ or if you would like to build a packaged wheel for installing in other environme
 
 ### Running Tests
 
-To make sure that everything works by running tests:
+#### C++ Tests
+
+To run the gtest C++ unit tests
+
+```shell
+./build.sh ctest
+```
+
+#### Python Tests
+
+To run the pytests
+
 ```shell
 cd tests
 pytest unit
@@ -158,10 +190,13 @@ pytest unit
 
 To build the documentation, simply run:
 ```shell
-python setup.py build_ext --inplace
-sphinx-build -E -a docs/ build/sphinx
+sphinx-build ./docs -a -E build/sphinx
 # View the docs
 open build/sphinx/index.html
+# View docs as served
+cd build/sphinx
+python -m http.server
+# Open localhost:8000 in browser
 ```
 
 ### Setting up Intellisense with clangd in Visual Studio Code

docs/index.rst

@@ -73,7 +73,6 @@ spatial intelligence research and applications.
    :maxdepth: 1
    :caption: Basic Concepts
 
-
 .. toctree::
    :maxdepth: 1
    :caption: API References