xo-umbrella: + docs support files

docs/glossary.rst

@@ -0,0 +1 @@
+scm = schematika

docs/install.rst

@@ -0,0 +1,107 @@
+.. _install:
+
+.. toctree
+   :maxdepth: 2
+
+Source
+======
+
+Source code for XO is on github `here`_
+
+.. _here: https://github.com/rconybea/xo-umbrella2
+
+This repo contains source to all the XO libraries,  in the most convenient form for
+building + installing all XO libraries, or developing changes to XO itself.
+
+Install
+=======
+
+This section explains how to build and install all XO libraries at once.
+If you only want to install a subset of XO, refer to build instructions for individual subsystems.
+You can build XO using cmake or nix.
+
+Dependencies
+------------
+
+XO dependencies (if you're using nix, it will assemble these for you)
+
+- cmake
+- llvm
+- libwebsockets
+- jsoncpp
+- eigen
+- catch2
+- pybind11
+
+XO documentation requires:
+
+- doxygen
+- graphviz
+- sphinx
+- sphinx-rtd-theme
+- breathe
+- sphinxcontrib-ditaa
+- sphinxcontrib-plantuml
+- pilllow
+
+cmake build
+-----------
+
+The cmake build has two phases.
+The first phase bootstraps some generated helper scripts used in the second phase.
+
+.. code-block::
+
+    $ git clone https://github.com/rconybea/xo-umbrella2
+    $ cd xo-umbrella2
+    $ PREFIX=/usr/local  # for example
+
+    # phase 1 -- install helper scripts
+    $ cmake -B .build0 -S xo-cmake -DCMAKE_INSTALL_PREFIX=$PREFIX
+    $ cmake --install .build0
+
+    # phase 2 -- build XO, using helpers installed in phase 1.
+    $ cmake -B .build -S . -DCMAKE_INSTALL_PREFIX=$PREFIX
+    $ cmake --build .build -j
+
+    # optionally build docs
+    $ cmake --build .build -- docs
+
+    $ cmake --install .build
+
+
+nix build
+---------
+
+Nix build uses toplevel ``default.nix``, along with ``pkgs/xo-foo.nix`` for each subsystem ``foo``.
+It ignores toplevel ``CMakeLists.txt``
+
+Build XO libraries, assemble sanbox under ``./result``
+
+.. code-block::
+
+    $ nixbuild -A xo-userenv
+
+
+Aternatively can enter nix environment, then follow instructions for cmake build:
+
+.. code-block::
+
+    $ nix-shell
+    $ /nix/store/<hash>-doxygen-1.10.0/bin/doxygen
+    # etc
+
+
+LSP Setup
+=========
+
+To setup xo-umbrella2 build to work with a language server:
+
+.. code-block::
+
+    $ cd xo-umbrella2
+    $ ln -s .build /compile_commands.json  # lsp will look for compile_commands.json in project root
+
+
+In this case subsystem LSP setup should be omitted, git root is ``path/to/xo-umbrella2``,
+not ``path/to/xo-umbrella2/xo-ratio`` etc.