From 0ee3128fcd98ca0f11a065f1e9ee56c97b30501b Mon Sep 17 00:00:00 2001 From: Yaraslau Tamashevich Date: Fri, 13 Dec 2024 15:23:29 +0200 Subject: [PATCH] Add documentation --- .github/workflows/docs.yml | 38 +++++++++++++++++++++++++++ .gitignore | 1 + CMakeLists.txt | 1 + docs/CMakeLists.txt | 50 ++++++++++++++++++++++++++++++++++++ docs/CNAME | 1 + docs/usage.md | 48 ++++++++++++++++++++++++++++++++++ src/Lightweight/SqlQuery.hpp | 16 +++++++----- 7 files changed, 149 insertions(+), 6 deletions(-) create mode 100644 .github/workflows/docs.yml create mode 100644 docs/CMakeLists.txt create mode 100644 docs/CNAME create mode 100644 docs/usage.md diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml new file mode 100644 index 00000000..cd2313aa --- /dev/null +++ b/.github/workflows/docs.yml @@ -0,0 +1,38 @@ +name: Docs + +on: + merge_group: + push: + branches: + - master + pull_request: + branches: + - master + + +concurrency: + group: docs-${{ github.ref }} + cancel-in-progress: true + +permissions: + contents: write +jobs: + create_documentation: + runs-on: ubuntu-24.04 + steps: + - name: Checkout + uses: actions/checkout@v4 + + - name: update apt + run: sudo apt -q update + - name: install dependencies + run: sudo apt install -y cmake ninja-build catch2 unixodbc-dev sqlite3 libsqlite3-dev libsqliteodbc valgrind uuid-dev g++-14 doxygen + - name: cmake configure + run: cmake --preset linux-gcc-release + - name: build + run: cmake --build --preset linux-gcc-release --target doc + + - name: Deploy 🚀 + uses: JamesIves/github-pages-deploy-action@v4 + with: + folder: html diff --git a/.gitignore b/.gitignore index 18379207..72544d08 100644 --- a/.gitignore +++ b/.gitignore @@ -9,3 +9,4 @@ vcpkg_installed/ CMakeSettings.json compile_commands.json *.sqlite +/html/ diff --git a/CMakeLists.txt b/CMakeLists.txt index 7a057643..e60fc99b 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -61,3 +61,4 @@ add_subdirectory(src/tools) enable_testing() add_subdirectory(src/tests) add_subdirectory(src/benchmark) +add_subdirectory(docs) diff --git a/docs/CMakeLists.txt b/docs/CMakeLists.txt new file mode 100644 index 00000000..d168f586 --- /dev/null +++ b/docs/CMakeLists.txt @@ -0,0 +1,50 @@ +find_package(Doxygen) + +if(DOXYGEN_FOUND) + message(STATUS "Doxygen found: ${DOXYGEN_EXECUTABLE}") + + FetchContent_Declare( + doxygen-awesome-css + GIT_REPOSITORY https://github.com/jothepro/doxygen-awesome-css.git + GIT_TAG v2.3.4 + ) + + FetchContent_MakeAvailable(doxygen-awesome-css) + + # Halide-specific Doxygen options + set(DOXYGEN_ALPHABETICAL_INDEX NO) + set(DOXYGEN_BUILTIN_STL_SUPPORT YES) + set(DOXYGEN_CASE_SENSE_NAMES NO) + set(DOXYGEN_CLASS_DIAGRAMS NO) + set(DOXYGEN_EXCLUDE bin) + set(DOXYGEN_EXTRACT_ALL NO) + set(DOXYGEN_EXTRACT_LOCAL_CLASSES NO) + set(DOXYGEN_FILE_PATTERNS *.hpp) + set(DOXYGEN_GENERATE_TREEVIEW YES) + set(DOXYGEN_HIDE_UNDOC_CLASSES YES) + set(DOXYGEN_HIDE_FRIEND_COMPOUNDS YES) + set(DOXYGEN_HIDE_IN_BODY_DOCS YES) + set(DOXYGEN_MARKDOWN_ID_STYLE GITHUB) + set(DOXYGEN_QT_AUTOBRIEF YES) + set(DOXYGEN_QUIET YES) + set(DOXYGEN_RECURSIVE YES) + set(DOXYGEN_REFERENCED_BY_RELATION YES) + set(DOXYGEN_REFERENCES_RELATION YES) + set(DOXYGEN_SORT_BY_SCOPE_NAME YES) + set(DOXYGEN_SORT_MEMBER_DOCS NO) + set(DOXYGEN_SOURCE_BROWSER YES) + set(DOXYGEN_STRIP_CODE_COMMENTS NO) + set(DOXYGEN_USE_MDFILE_AS_MAINPAGE "${PROJECT_SOURCE_DIR}/README.md") + set(DOXYGEN_HTML_EXTRA_STYLESHEET "${CMAKE_BINARY_DIR}/_deps/doxygen-awesome-css-src/doxygen-awesome.css") + set(DOXYGEN_OUTPUT_DIRECTORY "${PROJECT_SOURCE_DIR}") + set(DOXYGEN_EXCLUDE_SYMBOLS "detail,detail::*,std,std::*,benchmark,test") + + doxygen_add_docs(doc + "${PROJECT_SOURCE_DIR}/src;${PROJECT_SOURCE_DIR}/README.md;${PROJECT_SOURCE_DIR}/docs/usage.md" + ALL + COMMENT "Generate HTML documentation") + + +else() + message(WARNING "Doxygen not found, not generating documentation") +endif() diff --git a/docs/CNAME b/docs/CNAME new file mode 100644 index 00000000..bf13e0e0 --- /dev/null +++ b/docs/CNAME @@ -0,0 +1 @@ +www.lightweight.org diff --git a/docs/usage.md b/docs/usage.md new file mode 100644 index 00000000..a7b398ad --- /dev/null +++ b/docs/usage.md @@ -0,0 +1,48 @@ +# Examples + +# Configure connection to the database + +To connect to the database you need to provide connection string that library uses to establish connection and you can check if it alive in the following way +```c +SqlConnection::SetDefaultConnectionString(SqlConnectionString { + .value = std::format("DRIVER=SQLite3;Database={}", SqlConnectionString::SanitizePwd("Database.sqlite")) }); + +auto sqlConnection = SqlConnection(); +if (!sqlConnection.IsAlive()) +{ + std::println("Failed to connect to the database: {}", + SqlErrorInfo::fromConnectionHandle(sqlConnection.NativeHandle())); + std::abort(); +} +``` + +# Sql Query + +You can directly make a call to the database using `ExecuteDirect` function, for example +```c +auto stmt = SqlStatement {}; +stmt.ExecuteDirect(R"("SELECT "a", "b", "c" FROM "That" ORDER BY "That"."b" DESC)")); +while (stmt.FetchRow()) +{ + auto a = stmt.GetColumn(1); + auto b = stmt.GetColumn(2); + auto c = stmt.GetColumn(3); + std::println("{}|{}|{}", a, b,c); +} + +``` + +Or you can constuct statement using `SqlQueryBuilder` for different databases +```c +auto sqliteQueryBuilder = SqlQueryBuilder(formatter); +auto const sqlQuery = sqliteQueryBuilder.FromTable("That") + .Select() + .Fields("a", "b") + .Field("c") + .OrderBy(SqlQualifiedTableColumnName { .tableName = "That", .columnName = "b" }, + SqlResultOrdering::DESCENDING) + .All() + +``` + +For more info see `SqlQuery` and `SqlQueryFormatter` documentation diff --git a/src/Lightweight/SqlQuery.hpp b/src/Lightweight/SqlQuery.hpp index 261e42e8..23be2f2d 100644 --- a/src/Lightweight/SqlQuery.hpp +++ b/src/Lightweight/SqlQuery.hpp @@ -19,7 +19,9 @@ struct [[nodiscard]] SqlLastInsertIdQuery } }; -// API Entry point for building SQL queries. +///////////////////////////////////////////////// +/// API Entry point for building SQL queries. +///////////////////////////////////////////////// class [[nodiscard]] SqlQueryBuilder final { public: @@ -34,11 +36,13 @@ class [[nodiscard]] SqlQueryBuilder final // Constructs a new query builder for the given table with an alias. LIGHTWEIGHT_API SqlQueryBuilder& FromTableAs(std::string table, std::string alias); - // Initiates INSERT query building - // - // @param boundInputs Optional vector to store bound inputs. - // If provided, the inputs will be appended to this vector and can be used - // to bind the values to the query via SqlStatement::ExecuteWithVariants(...) + ///////////////////////////////////////////////// + /// Initiates INSERT query building + /// + /// @param boundInputs Optional vector to store bound inputs. + /// If provided, the inputs will be appended to this vector and can be used + /// to bind the values to the query via SqlStatement::ExecuteWithVariants(...) + ///////////////////////////////////////////////// LIGHTWEIGHT_API SqlInsertQueryBuilder Insert(std::vector* boundInputs = nullptr) noexcept; // Constructs a query to retrieve the last insert ID for the given table.