xo-umbrella: + docs support files

2025-06-22 16:19:21 -05:00 · 2025-06-22 16:19:21 -05:00 · f9961a1e37
commit f9961a1e37
parent b24d6d7e8d
8 changed files with 3148 additions and 0 deletions
--- a/Doxyfile.in
+++ b/Doxyfile.in
--- a/_static/img/favicon.ico
+++ b/_static/img/favicon.ico
--- a/_static/img/icon.svg
+++ b/_static/img/icon.svg
@ -0,0 +1,77 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!-- Created with Inkscape (http://www.inkscape.org/) -->
+
+<svg
+   width="108.32474mm"
+   height="108.39381mm"
+   viewBox="0 0 108.32474 108.39382"
+   version="1.1"
+   id="svg5"
+   inkscape:version="1.1.2 (0a00cf5339, 2022-02-04)"
+   sodipodi:docname="icon.svg"
+   xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
+   xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd"
+   xmlns="http://www.w3.org/2000/svg"
+   xmlns:svg="http://www.w3.org/2000/svg">
+  <sodipodi:namedview
+     id="namedview7"
+     pagecolor="#ffffff"
+     bordercolor="#666666"
+     borderopacity="1.0"
+     inkscape:pageshadow="2"
+     inkscape:pageopacity="0.0"
+     inkscape:pagecheckerboard="0"
+     inkscape:document-units="mm"
+     showgrid="false"
+     inkscape:zoom="1"
+     inkscape:cx="157"
+     inkscape:cy="322.5"
+     inkscape:window-width="1607"
+     inkscape:window-height="1085"
+     inkscape:window-x="26"
+     inkscape:window-y="23"
+     inkscape:window-maximized="0"
+     inkscape:current-layer="layer1"
+     fit-margin-top="9.8"
+     fit-margin-left="8"
+     fit-margin-right="10"
+     fit-margin-bottom="9.8" />
+  <defs
+     id="defs2" />
+  <g
+     inkscape:label="Layer 1"
+     inkscape:groupmode="layer"
+     id="layer1"
+     transform="translate(-47.453609,-27.112369)">
+    <circle
+       style="fill:#ff0000;fill-rule:evenodd;stroke-width:0.264583"
+       id="path31"
+       cx="68.211342"
+       cy="87.603088"
+       r="12.757732" />
+    <circle
+       style="fill:#ffcf00;fill-opacity:1;fill-rule:evenodd;stroke-width:0.264583"
+       id="path31-3"
+       cx="122.47422"
+       cy="49.670101"
+       r="12.757732" />
+    <circle
+       style="fill:#6b6bff;fill-opacity:1;fill-rule:evenodd;stroke-width:0.264583"
+       id="path31-3-6"
+       cx="133.02061"
+       cy="112.94845"
+       r="12.757732" />
+    <path
+       style="fill:none;stroke:#000000;stroke-width:2.5;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
+       d="M 73.144329,75.525772 C 85.051544,48.309278 109.54639,49.670102 109.54639,49.670102"
+       id="path589" />
+    <path
+       style="fill:none;stroke:#000000;stroke-width:2.44548;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
+       d="M 76.544292,96.598799 C 95.429921,116.11457 120.4897,113.37017 120.4897,113.37017"
+       id="path593" />
+    <path
+       style="fill:none;stroke:#000000;stroke-width:2.5;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
+       d="m 132,58.175257 c 17.01031,17.350515 7.14433,43.886603 7.14433,43.886603"
+       id="path788" />
+  </g>
+</svg>
--- a/_static/img/xo-icon.svg
+++ b/_static/img/xo-icon.svg
@ -0,0 +1,77 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!-- Created with Inkscape (http://www.inkscape.org/) -->
+
+<svg
+   width="108.32474mm"
+   height="108.39381mm"
+   viewBox="0 0 108.32474 108.39382"
+   version="1.1"
+   id="svg5"
+   inkscape:version="1.1.2 (0a00cf5339, 2022-02-04)"
+   sodipodi:docname="xo-icon.svg"
+   xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
+   xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd"
+   xmlns="http://www.w3.org/2000/svg"
+   xmlns:svg="http://www.w3.org/2000/svg">
+  <sodipodi:namedview
+     id="namedview7"
+     pagecolor="#ffffff"
+     bordercolor="#666666"
+     borderopacity="1.0"
+     inkscape:pageshadow="2"
+     inkscape:pageopacity="0.0"
+     inkscape:pagecheckerboard="0"
+     inkscape:document-units="mm"
+     showgrid="false"
+     inkscape:zoom="1"
+     inkscape:cx="157"
+     inkscape:cy="322.5"
+     inkscape:window-width="1607"
+     inkscape:window-height="1085"
+     inkscape:window-x="26"
+     inkscape:window-y="23"
+     inkscape:window-maximized="0"
+     inkscape:current-layer="layer1"
+     fit-margin-top="9.8"
+     fit-margin-left="8"
+     fit-margin-right="10"
+     fit-margin-bottom="9.8" />
+  <defs
+     id="defs2" />
+  <g
+     inkscape:label="Layer 1"
+     inkscape:groupmode="layer"
+     id="layer1"
+     transform="translate(-47.453609,-27.112369)">
+    <circle
+       style="fill:#ff0000;fill-rule:evenodd;stroke-width:0.264583"
+       id="path31"
+       cx="68.211342"
+       cy="87.603088"
+       r="12.757732" />
+    <circle
+       style="fill:#ffcf00;fill-opacity:1;fill-rule:evenodd;stroke-width:0.264583"
+       id="path31-3"
+       cx="122.47422"
+       cy="49.670101"
+       r="12.757732" />
+    <circle
+       style="fill:#6b6bff;fill-opacity:1;fill-rule:evenodd;stroke-width:0.264583"
+       id="path31-3-6"
+       cx="133.02061"
+       cy="112.94845"
+       r="12.757732" />
+    <path
+       style="fill:none;stroke:#000000;stroke-width:2.5;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
+       d="M 73.144329,75.525772 C 85.051544,48.309278 109.54639,49.670102 109.54639,49.670102"
+       id="path589" />
+    <path
+       style="fill:none;stroke:#000000;stroke-width:2.44548;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
+       d="M 76.544292,96.598799 C 95.429921,116.11457 120.4897,113.37017 120.4897,113.37017"
+       id="path593" />
+    <path
+       style="fill:none;stroke:#000000;stroke-width:2.5;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
+       d="m 132,58.175257 c 17.01031,17.350515 7.14433,43.886603 7.14433,43.886603"
+       id="path788" />
+  </g>
+</svg>
--- a/conf.py
+++ b/conf.py
@ -0,0 +1,46 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# For the full list of built-in configuration values, see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+
+project = 'xo documentation'
+copyright = '2025, Roland Conybeare'
+author = 'Roland Conybeare'
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+#extensions = []
+extensions = [ "breathe",
+               "sphinx.ext.mathjax",     # inline math
+               "sphinx.ext.autodoc",     # generate info from docstrings
+               "sphinxcontrib.ditaa",    # diagrams-through-ascii-art
+               "sphinxcontrib.plantuml", # text -> uml diagrams
+              ]
+
+# note: breathe requires doxygen xml output -> must have GENERATE_XML = YES in Doxyfile.in
+#       match project name in Doxyfile.in
+breathe_default_project = "xodoxxml"
+
+# Not sure if we need breather here, since we're composing on top of
+# independent sphinx projects
+#
+# note: breathe requires doxygen xml output -> must have GENERATE_XML = YES in Doxyfile.in
+#       match project name in Doxyfile.in
+#breathe_default_project = "xodoxxml"
+
+templates_path = ['_templates']
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+
+pygments_style = 'sphinx'
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+#html_theme = 'alabaster'
+html_theme = 'sphinx_rtd_theme'
+html_static_path = ['_static']
+html_favicon = '_static/img/favicon.ico'
--- a/docs/glossary.rst
+++ b/docs/glossary.rst
@ -0,0 +1 @@
+scm = schematika
--- a/docs/install.rst
+++ b/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.
--- a/index.rst
+++ b/index.rst
@ -0,0 +1,21 @@
+
+XO Documentation
+================
+
+Welcome to XO.  XO provides a set of integrated libraries for event-based simulation,
+Intended for use in C++ and python applications.
+
+Some features: kalman filters, stochastic processes, complex event processing, simulation, websockets.
+
+.. toctree::
+   :maxdepth: 2
+   :caption: XO contents
+
+   docs/install
+   xo-flatstring/docs/index
+   xo-ratio/docs/index
+   xo-unit/docs/index
+   xo-tokenizer/docs/index
+   xo-jit/docs/index
+   genindex
+   search