From a52d7554f351f603a4f941b7a923aabab6eac91d Mon Sep 17 00:00:00 2001 From: Roland Conybeare Date: Sun, 13 Jul 2025 21:18:15 -0500 Subject: [PATCH] xo-indentlog: doc: add indentlog docs [WIP] --- index.rst | 1 + xo-indentlog/docs/CMakeLists.txt | 9 ++ xo-indentlog/docs/README | 41 ++++++ xo-indentlog/docs/conf.py | 39 ++++++ xo-indentlog/docs/glossary.rst | 11 ++ xo-indentlog/docs/index.rst | 19 +++ xo-indentlog/docs/install.rst | 170 +++++++++++++++++++++++ xo-indentlog/docs/logging_impl.rst | 65 +++++++++ xo-indentlog/docs/logging_intro.rst | 57 ++++++++ xo-indentlog/docs/ppconfig-reference.rst | 33 +++++ xo-indentlog/docs/ppstr-reference.rst | 36 +++++ xo-indentlog/docs/pretty_impl.rst | 37 +++++ xo-indentlog/docs/scope-reference.rst | 43 ++++++ 13 files changed, 561 insertions(+) create mode 100644 xo-indentlog/docs/CMakeLists.txt create mode 100644 xo-indentlog/docs/README create mode 100644 xo-indentlog/docs/conf.py create mode 100644 xo-indentlog/docs/glossary.rst create mode 100644 xo-indentlog/docs/index.rst create mode 100644 xo-indentlog/docs/install.rst create mode 100644 xo-indentlog/docs/logging_impl.rst create mode 100644 xo-indentlog/docs/logging_intro.rst create mode 100644 xo-indentlog/docs/ppconfig-reference.rst create mode 100644 xo-indentlog/docs/ppstr-reference.rst create mode 100644 xo-indentlog/docs/pretty_impl.rst create mode 100644 xo-indentlog/docs/scope-reference.rst diff --git a/index.rst b/index.rst index c33d6377..221b7bea 100644 --- a/index.rst +++ b/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 diff --git a/xo-indentlog/docs/CMakeLists.txt b/xo-indentlog/docs/CMakeLists.txt new file mode 100644 index 00000000..a04c884c --- /dev/null +++ b/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 +) diff --git a/xo-indentlog/docs/README b/xo-indentlog/docs/README new file mode 100644 index 00000000..6aff5d41 --- /dev/null +++ b/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 diff --git a/xo-indentlog/docs/conf.py b/xo-indentlog/docs/conf.py new file mode 100644 index 00000000..a598d229 --- /dev/null +++ b/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' diff --git a/xo-indentlog/docs/glossary.rst b/xo-indentlog/docs/glossary.rst new file mode 100644 index 00000000..82bd0d2d --- /dev/null +++ b/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` diff --git a/xo-indentlog/docs/index.rst b/xo-indentlog/docs/index.rst new file mode 100644 index 00000000..8a974b60 --- /dev/null +++ b/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 diff --git a/xo-indentlog/docs/install.rst b/xo-indentlog/docs/install.rst new file mode 100644 index 00000000..7e075e35 --- /dev/null +++ b/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 + #include + +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) diff --git a/xo-indentlog/docs/logging_impl.rst b/xo-indentlog/docs/logging_impl.rst new file mode 100644 index 00000000..f5d0f91c --- /dev/null +++ b/xo-indentlog/docs/logging_impl.rst @@ -0,0 +1,65 @@ +.. _logging_impl: + +Logging Components +================== + +Install instructions :doc:`here` + +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 + + +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 diff --git a/xo-indentlog/docs/logging_intro.rst b/xo-indentlog/docs/logging_intro.rst new file mode 100644 index 00000000..acd76449 --- /dev/null +++ b/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 diff --git a/xo-indentlog/docs/ppconfig-reference.rst b/xo-indentlog/docs/ppconfig-reference.rst new file mode 100644 index 00000000..f511abde --- /dev/null +++ b/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 + +Class +----- + +Configuration for pretty printing + +.. doxygenclass:: xo::print::ppconfig + +Member Variables +---------------- + +.. doxygengroup:: ppconfig-instance-vars diff --git a/xo-indentlog/docs/ppstr-reference.rst b/xo-indentlog/docs/ppstr-reference.rst new file mode 100644 index 00000000..a8f24034 --- /dev/null +++ b/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 + +Types +----- + +.. doxygenclass:: xo::ppconcat + +Functions +--------- + +.. doxygenfunction:: xo::toppstr + +.. doxygenfunction:: xo::toppstr2 diff --git a/xo-indentlog/docs/pretty_impl.rst b/xo-indentlog/docs/pretty_impl.rst new file mode 100644 index 00000000..45e08575 --- /dev/null +++ b/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 + ppconfig class diff --git a/xo-indentlog/docs/scope-reference.rst b/xo-indentlog/docs/scope-reference.rst new file mode 100644 index 00000000..abf199ae --- /dev/null +++ b/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 + +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