xo-indentlog: doc: add indentlog docs [WIP]

index.rst

@@ -12,6 +12,7 @@ Some features: kalman filters, stochastic processes, complex event processing, s
    :caption: XO contents
 
    docs/install
+   xo-indentlog/docs/index
    xo-flatstring/docs/index
    xo-ratio/docs/index
    xo-unit/docs/index

xo-indentlog/docs/CMakeLists.txt

@@ -0,0 +1,9 @@
+# xo-indentlog/docs/CMakeLists.txt
+
+xo_doxygen_collect_deps()
+xo_docdir_doxygen_config()
+xo_docdir_sphinx_config(
+    index.rst install.rst
+    logging_impl.rst
+    pretty_impl.rst ppconfig-reference.rst ppstr-reference.rst
+)

xo-indentlog/docs/README

@@ -0,0 +1,41 @@
+standalone build
+
+        +-----------------------------------------------+
+        | cmake                                         |
+        |   CMakeLists.txt                              |
+        |   $PREFIX/share/cmake/xo_macros/xo_cxx.cmake  |
+        +-----------------------------------------------+
+           |
+           |                                                  +----------------------+
+           +------------------------------------------------->| .build/docs/Doxyfile |
+           |                                                  +----------------------+
+           |                                                     ^
+           |                                 (cmake)             |
+           |                                        /------------/
+           |                                        |
+           |     +---------------------------------------+          +-----------------+
+           +---->| doxygen                               |--------->| .build/docs/dox |
+           |     |   $PREFIX/share/xo-macros/Doxyfile.in | (doxygen)|   +- html/      |
+           |     +---------------------------------------+          |   +- xml/       |
+           |                                                        +-----------------+
+           |                                                             |
+           |                                                             |(sphinx)
+           |                                                             |
+           |                                                             v
+           |     +---------------------------------------+        +--------------------+
+           \---->| sphinx                                |------->| .build/docs/sphinx |
+                 |   +- conf.py                          |        |   +- html/         |
+                 |   +- _static/                         |        +--------------------+
+                 |   +- *.rst                            |
+                 +---------------------------------------+
+
+umbrella build relies on top-level cmake macros
+
+files
+
+   README            this file
+   CMakeLists.txt    build entry point
+   conf.py           sphinx config
+   _static           static files for sphinx
+
+   index.rst         toplevel sphinx document; entry point

xo-indentlog/docs/conf.py

@@ -0,0 +1,39 @@
+# 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 reader documentation'
+copyright = '2024-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"
+
+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'

xo-indentlog/docs/glossary.rst

@@ -0,0 +1,11 @@
+.. _glossary:
+
+Glossary
+--------
+
+.. glossary::
+    pp
+      | Short for `pretty printer`.  For example in `ppdetail`, `toppstr`.
+
+    xtag
+      | Shorthand for `tag with preceding space`

xo-indentlog/docs/index.rst

@@ -0,0 +1,19 @@
+.. xo-indentlog documentation master file.
+
+xo-indentlog documentation
+==========================
+
+xo-indentlog is a header-only library for human-readable structured logging
+and general purpose pretty-printing.
+
+.. toctree::
+   :maxdepth: 2
+   :caption: xo-indentlog contents
+
+   install
+   logging_intro
+   logging_impl
+   pretty_impl
+   glossary
+   genindex
+   search

xo-indentlog/docs/install.rst

@@ -0,0 +1,170 @@
+.. _install:
+
+.. toctree::
+   :maxdepth: 2
+
+Source
+======
+
+Source code lives on github `here`_
+
+.. _here: https://github.com/rconybea/indentlog
+
+To clone from git:
+
+.. code-block:: bash
+
+    git clone https://github.com/rconybea/indentlog xo-indentlog
+
+Tested with gcc 13.3
+
+Install
+=======
+
+Since ``xo-indentlog`` is header-only, can incorporate into another project by simply copying the
+include directories to somewhere convenient
+
+Copy includes
+-------------
+
+.. code-block:: bash
+
+    # for example
+    cd myproject
+    mkdir -p ext/xo-indentlog
+    rsync -a -v path/to/xo-indentlog/include/ ext/xo-indentlog/
+
+Include as git submodule
+------------------------
+
+.. code-block::bash
+
+    cd myproject
+    git submodule add -b main https://github.com/rconybea/indentlog ext/xo-indentlog
+    git submodule update --init ext/xo-indentlog
+
+This assumes you organize directly-incorporated dependencies under directory ``myproject/ext``.
+You would then add ``myproject/ext/xo-indentlog/include`` to your compiler's include path,
+and from c++ do something like
+
+.. code-block:: c++
+
+    #include <xo/indentlog/scope.hpp>
+    #include <xo/indentlog/print/pretty.hpp>
+
+in c++ source files that rely on xo-indentlog and pretty printing
+
+Install along with XO
+---------------------
+
+Install along with the rest of *XO* from `xo-umbrella2 source`_
+
+.. _xo-umbrella2 source: https://github.com/rconybea/xo-umbrella2
+
+(instructions in xo-umbrella2/README.md)
+
+Building from source
+--------------------
+
+Although the xo-indentlog library is header-only, unit tests and examples have additional dependencies.
+Example instructions for build strating from stock ubuntu (i.e. github CI) are in `ubuntu-main.yml`_
+
+.. _ubuntu-main.yml: https://github.com/Rconybea/indentlog/blob/main/.github/workflows/ubuntu-main.yml
+
+Unit-test and example dependencies:
+
+* `catch2`_ header-only unit-test framework
+* `xo-cmake`_ cmake macros (shared with other XO projects)
+
+.. _catch2: https://github.com/catchorg/Catch2
+.. _xo-cmake: https://github.com/rconybea/xo-cmake
+
+To build documentation, will also need:
+
+* `doxygen`
+* `graphviz`
+* `sphinx`
+* `breathe`
+* `sphinx_rtd_theme`
+* `sphinxcontrib.ditaa`
+
+Preamble:
+
+.. code-block:: bash
+
+    mkdir -p ~/proj/xo
+    cd ~/proj/xo
+
+    git clone https://github/com/rconybea/xo-cmake
+
+    PREFIX=/usr/local
+
+    # want PREFIX/bin in PATH to use xo-cmake helpers
+    PATH=$PREFIX/bin:$PATH
+
+Install `xo-cmake`:
+
+.. code-block:: bash
+
+    cmake -B xo-cmake/.build -S xo-cmake
+    cmake --install xo-cmake/.build
+    xo-build --clone --configure --build --install xo-indentlog
+
+    # or with optional components
+    xo-build --clone --configure --build --install --with-examples --with-utests xo-indentlog
+
+Note that you can instead have ``xo-build`` tell you what it /would/ do:
+
+.. code-block:: bash
+
+    xo-build --configure -dry-run xo-indentlog
+    cmake -DCMAKE_INSTALL_PREFIX=/usr/local -DCMAKE_MODULE_PATH=/usr/local/share/cmake -S xo-indentlog -B xo-indentlog/.build -DENABLE_TESTING=1 -DXO_ENABLE_EXAMPLES=1 -DCMAKE_BUILD_TYPE=Debug
+
+
+Directories under ``PREFIX`` will then contain:
+
+.. code-block::
+
+    PREFIX
+    +- bin
+    |  +- xo-build
+    |  +- xo-cmake-config
+    |  \- xo-cmake-lcov-harness
+    +- include
+    |  \- xo
+    |     \- indentlog/
+    +- lib
+    |  \- cmake
+    |     +- indentlog/
+    +- share
+       +- cmake
+       |  \- xo_macros
+       |     +- code-coverage.cmake
+       |     +- xo-project-macros.cmake
+       |     \- xo_cxx.cmake
+       +- etc
+       |  \- xo
+       |     \- subsystem-list
+       \- xo-macros
+          +- Doxyfile.in
+          +- gen-ccov.in
+          \- xo-bootstrap-macros.cmake
+
+CMake Support
+-------------
+
+To use built-in cmake support to use installed ``xo-indentlog`` from another project:
+
+Make sure ``PREFIX/lib/cmake`` is searched by cmake (for example include it in ``CMAKE_PREFIX_PATH``)
+
+Add to your ``CMakeLists.txt``:
+
+.. code-block:: cmake
+
+    FindPackage(indentlog CONFIG REQUIRED)
+    target_link_libraries(mytarget INTERFACE indentlog)
+
+Supported compilers
+-------------------
+
+* developed with gcc 13.2.0;  github CI using gcc 11.4.0 (asof April 2024)

xo-indentlog/docs/logging_impl.rst

@@ -0,0 +1,65 @@
+.. _logging_impl:
+
+Logging Components
+==================
+
+Install instructions :doc:`here<install>`
+
+Abstraction tower for *xo-indentlog* logging components:
+
+.. ditaa::
+    :--scale: 0.85
+
+    +------------------------------------------+
+    |               basic_scope                |
+    +------------------------------------------+
+    |                state_impl                |
+    +-----------------------+------------------+
+    |                       |     log_config   |
+    |      log_streambuf    +------------------+
+    |                       |     log_level    |
+    +-----------------------+------------------+
+
+**basic_scope**
+    Primary entry point for scope-indented logging.
+    Lightweight with RAII semantics.
+
+**state_impl**
+    Bookkeeping for internal state, managed by ``basic_scope``.
+
+**log_streambuf**
+    Custom streambuf implementation, buffering in memory.
+
+**log_config**
+    Logging configuration, to control formatting behavior.
+
+**log_level**
+    Categorize log messages by importance for filtering.
+
+.. toctree::
+   :maxdepth: 2
+
+   xo::scope <scope-reference>
+
+
+Log_streambuf
+-------------
+
+Indentlog relies on a custom ``std::streambuf`` implementation, ``xo::log_streambuf``.
+log_streambuf captures content in an internal vector, expanding it on demand.
+To support pretty-printing, log_streambuf tracks current position relative to left margin
+
+.. uml::
+    :caption: log_streambuf
+    :scale: 99%
+    :align: center
+
+    class streambuf {
+    }
+
+    class log_streambuf {
+    - solpos_: size_t
+    - buf_v_: vector
+    }
+
+    streambuf <|-- log_streambuf

xo-indentlog/docs/logging_intro.rst

@@ -0,0 +1,57 @@
+.. _logging-intro:
+
+Introduction
+============
+
+Indentlog provides is a logging library that autoindents to reveal the calling program's call graph.
+
+Features
+--------
+
+* **Indenting** Nesting level and is consistent with program structure.
+
+* **Pretty-Printer** Includes configurable, general-purpose pretty-printer.
+
+* **Efficient** Uses custom streambuf for efficiency.
+  Avoids executing code to assemble input values that would be discarded below currently configured
+  logging level
+
+* **Configurable** configure from global configuration object `logconfig`.
+
+* **Thread-aware** logging state is accessed from thread-local variables.
+  Logging for different threads is assembled in thread-local state for improved concurrency.
+
+* **Colorized** generate colorized output, depending on configuration.
+
+Examples
+--------
+
+.. code-block:: cpp
+
+    #include "xo/indentlog/scope.hpp"
+
+    using namespace xo;
+
+    void inner(int x) {
+        scope log(XO_ENTER0(always), ":x ", x);
+    }
+
+    void outer(int y) {
+        scope log(XO_ENTER0(always), ":y ", y);
+
+        inner(2*y);
+    }
+
+    int
+    main(int argc, char ** argv) {
+        outer(123);
+    }
+
+output:
+
+.. code-block:: text
+
+    15:28:35.702611 +(0) outer :y 123                                               [ex1.cpp:12]
+    15:28:35.702723   +(1) inner :x 246                                             [ex1.cpp:8]
+    15:28:35.702737   -(1) inner
+    15:28:35.702760 -(0) outer

xo-indentlog/docs/ppconfig-reference.rst

@@ -0,0 +1,33 @@
+.. _ppconfig-reference:
+
+Ppconfig Reference
+==================
+
+.. ditaa::
+    :--scale: 0.85
+
+    +--------------------+
+    |      toppstr       |
+    +--------------------+
+    |      ppdetail      |
+    +--------------------+
+    |      ppstate       |
+    +--------------------+
+    |cBLU  ppconfig      |
+    +--------------------+
+
+.. code-block:: cpp
+
+    #include <xo/indentlog/ppconfig.hpp>
+
+Class
+-----
+
+Configuration for pretty printing
+
+.. doxygenclass:: xo::print::ppconfig
+
+Member Variables
+----------------
+
+.. doxygengroup:: ppconfig-instance-vars

xo-indentlog/docs/ppstr-reference.rst

@@ -0,0 +1,36 @@
+.. _ppstr-reference:
+
+.. toctree::
+   :maxdepth: 2
+
+Ppstr Reference
+===============
+
+.. ditaa::
+    :--scale: 0.85
+
+    +--------------------+
+    |cBLU    ppstr       |
+    +--------------------+
+    |      ppdetail      |
+    +--------------------+
+    |      ppstate       |
+    +--------------------+
+    |      ppconfig      |
+    +--------------------+
+
+.. code-block:: cpp
+
+    #include <xo/indentlog/ppstr.hpp>
+
+Types
+-----
+
+.. doxygenclass:: xo::ppconcat
+
+Functions
+---------
+
+.. doxygenfunction:: xo::toppstr
+
+.. doxygenfunction:: xo::toppstr2

xo-indentlog/docs/pretty_impl.rst

@@ -0,0 +1,37 @@
+.. _pretty_impl:
+
+Pretty Printer
+==============
+
+Abstraction tower for *xo-indentlog* pretty-printer:
+
+.. ditaa::
+    :--scale: 0.85
+
+    +--------------------+
+    |      toppstr       |
+    +--------------------+
+    |      ppdetail      |
+    +--------------------+
+    |      ppstate       |
+    +--------------------+
+    |      ppconfig      |
+    +--------------------+
+
+**toppstr**
+    Pretty print arguments to string.
+
+**ppdetail**
+    Template for Type-specific pretty-printing.
+
+**ppstate**
+    Temporary state object. Created once for each top-level pretty-print call
+
+**ppconfig**
+    Pretty-printer configuration.
+
+.. toctree::
+   :maxdepth: 1
+
+   ppstr functions <ppstr-reference>
+   ppconfig class <ppconfig-reference>

xo-indentlog/docs/scope-reference.rst

@@ -0,0 +1,43 @@
+.. _scope-reference:
+
+.. toctree::
+   :maxdepth: 2
+
+Scope Reference
+===============
+
+.. ditaa::
+    :--scale: 0.85
+
+    +------------------------------------------+
+    |cBLU           basic_scope                |
+    +------------------------------------------+
+    |                state_impl                |
+    +-----------------------+------------------+
+    |                       |     log_config   |
+    |      log_streambuf    +------------------+
+    |                       |     log_level    |
+    +-----------------------+------------------+
+
+.. code-block:: cpp
+
+    #include <xo/indentlog/scope.hpp>
+
+Convenience Macros
+------------------
+
+.. doxygendefine:: XO_SCOPE
+
+Classes
+-------
+
+.. doxygenclass:: xo::scope_setup
+
+Application code isn't expected to interact with this class directly
+
+.. doxygengroup:: scope_setup-instance-vars
+
+Basic Scope
+~~~~~~~~~~~
+
+.. doxygenclass:: xo::basic_scope