roland/xo-alloc
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

xo-reader: + docs scaffold

Browse source
This commit is contained in:
Roland Conybeare 2025-07-04 10:09:04 -05:00
commit 2025969068
14 changed files with 251 additions and 10 deletions
Download patch file Download diff file Expand all files Collapse all files

2
CMakeLists.txt
View file

@ -116,6 +116,6 @@ add_subdirectory(xo-pyjit)
# ----------------------------------------------------------------
# documentation. must follow add_subdirectory() for satellite projects
xo_umbrella_doxygen_deps(xo_flatstring xo_ratio xo_unit xo_tokenizer xo_jit)
xo_umbrella_doxygen_deps(xo_flatstring xo_ratio xo_unit xo_tokenizer xo_reader xo_jit)
xo_umbrella_doxygen_config()
xo_umbrella_sphinx_config(index.rst docs/install.rst docs/glossary.rst)

1
index.rst
View file

@ -16,6 +16,7 @@ Some features: kalman filters, stochastic processes, complex event processing, s
xo-ratio/docs/index
xo-unit/docs/index
xo-tokenizer/docs/index
xo-reader/docs/index
xo-jit/docs/index
glossary
genindex

9
xo-reader/CMakeLists.txt
View file

@ -19,9 +19,12 @@ add_definitions(${PROJECT_CXX_FLAGS})
# ----------------------------------------------------------------
add_subdirectory(src/reader)
add_subdirectory(examples)
add_subdirectory(utest)
xo_export_cmake_config(${PROJECT_NAME} ${PROJECT_VERSION} ${PROJECT_NAME}Targets)
# ----------------------------------------------------------------
# provide find_package() support
xo_export_cmake_config(${PROJECT_NAME} ${PROJECT_VERSION} ${PROJECT_NAME}Targets)
# docs targets depends on other library/utest/exec targets,
# must come after them
#
add_subdirectory(docs)

7
xo-reader/docs/CMakeLists.txt Normal file
View file

@ -0,0 +1,7 @@
# xo-reader/docs/CMakeLists.txt
xo_doxygen_collect_deps()
xo_docdir_doxygen_config()
xo_docdir_sphinx_config(
index.rst
)

41
xo-reader/docs/README Normal file
View file

@ -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 | | +- html/ |
| +---------------------------------------+ | +- xml/ |
| +-----------------+
| |
| /------------/
| |
| 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

1
xo-reader/docs/_static/README vendored Normal file
View file

@ -0,0 +1 @@
add any static {.html, .js, ..} files for sphinx to pickup here

BIN
xo-reader/docs/_static/img/favicon.ico vendored Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 302 KiB

39
xo-reader/docs/conf.py Normal file
View file

@ -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'

45
xo-reader/docs/example.rst Normal file
View file

@ -0,0 +1,45 @@
.. _examples:
.. toctree::
:maxdepth: 2
Examples
========
See ``xo-reader/examples`` for built examples
.. code-block:: cpp
:linenos:
#include "xo/reader/reader.h"
int
main() {
using namespace xo::scm;
using namespace std;
reader rdr;
rdr.begin_translation_unit();
bool eof = false;
while (!eof) {
auto input = ins.read_some();
eof = ins.eof();
for (auto rem = input; !rem.empty();) {
// res: (parsed-expr, used)
auto [expr, rem2] = rdr.read_expr(rem, eof);
if (expr) {
cout << expr << endl;
}
rem = rem.suffix_after(rem2);
}
}
if (rdr.has_prefix()) {
cout << "error: unparsed input after expression" << endl;
}
}

12
xo-reader/docs/index.rst Normal file
View file

@ -0,0 +1,12 @@
.. xo-reader documentation master file.
xo-reader documentation
=======================
xo-reader provides a parser for the Schematika language.
.. toctree::
:maxdepth: 2
:caption: xo-reader contents
example

4
xo-tokenizer/docs/CMakeLists.txt
View file

@ -4,6 +4,6 @@ xo_doxygen_collect_deps()
xo_docdir_doxygen_config()
xo_docdir_sphinx_config(
index.rst install.rst examples.rst implementation.rst
token-class.rst tokenizer-error-class.rst span-class.rst tokentype-enum.rst
input-state.rst
input-state-class.rst scan-result-class.rst schematika-tokens.rst span-class.rst
token-class-rst tokenizer-error-class.rst tokentype-enum.rst
)

6
xo-tokenizer/docs/README
View file

@ -9,10 +9,10 @@ standalone build
| +----------------------+
+------------------------------------------------->| .build/docs/Doxyfile |
| +----------------------+
| |
| ^
| (cmake |
| /------------/
| |
| v
| +---------------------------------------+ +-----------------+
+---->| doxygen |--->| .build/docs/dox |
| | $PREFIX/share/xo-macros/Doxyfile.in | | +- html/ |
@ -37,3 +37,5 @@ files
CMakeLists.txt build entry point
conf.py sphinx config
_static static files for sphinx
index.rst toplevel sphinx document; entry point

92
xo-tokenizer/docs/schematika-tokens.rst
View file

@ -11,5 +11,95 @@ Schematika Tokens
- examples
- description
* - tk_i64
- 123, -8,
- ``123``, ``-8``
- 64-bit integer literal
* - tk_f64
- ``1.234``, ``-10``., ``-1.981e-10``, ``3e6``
- 64-bit floating-point literal
* - tk_string
- ``"hello"``, ``"Q: \"what's up?\"\nA: \"parsing!\""``
- string literal. Usual escapes ``\n``, ``\r``, ``\t``, ``\"``, ``\\``
* - tk_symbol
- ``apple``, ``funKy``, ``x123``, ``_mumble``, ``hyphenated-var``
- symbol name
* - tk_type
- ``type``
- keyword
* - tk_def
- ``def``
- keyword
* - tk_lambda
- ``lambda``
- keyword
* - tk_if
- ``if``
- keyword
* - tk_let
- ``let``
- keyword
* - tk_in
- ``in``
- keyword
* - tk_end
- ``end``
- keyword
* - tk_leftparen
- ``(``
-
* - tk_rightparen
- ``)``
-
* - tl_leftbracket
- ``[``
-
* - tk_rightbracket
- ``]``
-
* - tk_leftbrace
- ``{``
-
* - tk_rightbrace
- ``}``
-
* - tk_leftangle
- ``<``
-
* - tk_rightangle
- ``>``
-
* - tk_dot
- ``.``
-
* - tk_comma
- ``,``
-
* - tk_colon
- ``:``
-
* - tk_doublecolon
- ``::``
-
* - tk_semicolon
- ``;``
-
* - tk_singleassign
- ``=``
-
* - tk_assign
- ``:=``
-
* - tk_yields
- ``->``
-
* - tk_plus
- ``+``
- allowed in symbol
* - tk_minus
- ``-``
- allowed in symbol
* - tk_star
- ``*``
- allowed in symbol
* - tk_slash
- ``/``
- allowed in symbol

2
xo-tokenizer/example/tokenrepl/tokenrepl.cpp
View file

@ -1,4 +1,4 @@
/** @file tokenrepl.cp **/
/** @file tokenrepl.cpp **/
#include "xo/tokenizer/tokenizer.hpp"
#include <iostream>