improve documentation

CMakeLists.txt

@@ -145,6 +145,7 @@ endif ()
 
 if (QUILL_BUILD_EXAMPLES)
     add_subdirectory(examples)
+    add_subdirectory(docs/examples)
 endif ()
 
 if (QUILL_BUILD_BENCHMARKS)
@@ -389,5 +390,9 @@ if (QUILL_MASTER_PROJECT OR QUILL_ENABLE_INSTALL)
 endif ()
 
 if (QUILL_DOCS_GEN)
+    if (NOT QUILL_BUILD_EXAMPLES)
+        message(FATAL_ERROR "QUILL_DOCS_GEN requires QUILL_BUILD_EXAMPLES to be ON. Please enable QUILL_BUILD_EXAMPLES.")
+    endif()
+
     add_subdirectory(docs)
 endif ()

docs/Doxyfile.in

@@ -810,7 +810,7 @@ WARNINGS               = YES
 # will automatically be disabled.
 # The default value is: YES.
 
-WARN_IF_UNDOCUMENTED   = YES
+WARN_IF_UNDOCUMENTED   = NO
 
 # If the WARN_IF_DOC_ERROR tag is set to YES, doxygen will generate warnings for
 # potential errors in the documentation, such as not documenting some parameters

docs/backend_options.rst

@@ -7,8 +7,6 @@ The backend options allow you to customize the behavior of the backend thread an
 
 For example, to pin the backend worker thread to a specific CPU, you can use the following code:
 
-.. code:: cpp
-
-    quill::BackendOptions backend_options;
-    backend_options.cpu_affinity = 5;
-    quill::Backend::start(backend_options);
+.. literalinclude:: examples/quill_docs_example_backend_options.cpp
+   :language: cpp
+   :linenos:

docs/backtrace_logging.rst

@@ -22,59 +22,13 @@ To manually flush backtrace logs, call :cpp:func:`LoggerImpl::flush_backtrace`.
 Store messages in the ring buffer and display them when ``LOG_ERROR`` is logged
 -------------------------------------------------------------------------------
 
-.. code:: cpp
-
-    // a LOG_ERROR(...) or higher severity log message occurs via this logger.
-    // Enable the backtrace with a max ring buffer size of 2 messages which will get flushed when
-    // Backtrace has to be enabled only once in the beginning before calling LOG_BACKTRACE(...) for the first time.
-    logger->init_backtrace(2, quill::LogLevel::Error);
-
-    LOG_INFO(logger, "BEFORE backtrace Example {}", 1);
-
-    LOG_BACKTRACE(logger, "Backtrace log {}", 1);
-    LOG_BACKTRACE(logger, "Backtrace log {}", 2);
-    LOG_BACKTRACE(logger, "Backtrace log {}", 3);
-    LOG_BACKTRACE(logger, "Backtrace log {}", 4);
-
-    // Backtrace is not flushed yet as we requested to flush on errors
-    LOG_INFO(logger, "AFTER backtrace Example {}", 1);
-
-    // log message with severity error - This will also flush_sink the backtrace which has 2 messages
-    LOG_ERROR(logger, "An error has happened, Backtrace is also flushed.");
-
-    // The backtrace is flushed again after LOG_ERROR but in this case it is empty
-    LOG_ERROR(logger, "An second error has happened, but backtrace is now empty.");
-
-    // Log more backtrace messages
-    LOG_BACKTRACE(logger, "Another Backtrace log {}", 1);
-    LOG_BACKTRACE(logger, "Another Backtrace log {}", 2);
-
-    // Nothing is logged at the moment
-    LOG_INFO(logger, "Another log info");
-
-    // Still nothing logged - the error message is on a different logger object
-    quill::LoggerImpl* logger_2 = quill::get_logger("example_1_1");
-
-    LOG_CRITICAL(logger_2, "A critical error from different logger.");
-
-    // The new backtrace is flushed again due to LOG_CRITICAL
-    LOG_CRITICAL(logger, "A critical error from the logger we had a backtrace.");
+.. literalinclude:: examples/quill_docs_example_backtrace_logging_1.cpp
+   :language: cpp
+   :linenos:
 
 Store messages in the ring buffer and display them on demand
 ------------------------------------------------------------
 
-.. code:: cpp
-
-    // Store maximum of two log messages. By default they will never be flushed since no LogLevel severity is specified
-    logger->init_backtrace(2);
-
-    LOG_INFO(logger, "BEFORE backtrace Example {}", 2);
-
-    LOG_BACKTRACE(logger, "Backtrace log {}", 100);
-    LOG_BACKTRACE(logger, "Backtrace log {}", 200);
-    LOG_BACKTRACE(logger, "Backtrace log {}", 300);
-
-    LOG_INFO(logger, "AFTER backtrace Example {}", 2);
-
-    // an error has happened - flush the backtrace manually
-    logger->flush_backtrace();
+.. literalinclude:: examples/quill_docs_example_backtrace_logging_2.cpp
+   :language: cpp
+   :linenos:

docs/basic_example.rst

@@ -3,25 +3,9 @@
 Basic Example
 =============
 
-.. code:: cpp
-
-    #include "quill/Backend.h"
-    #include "quill/Frontend.h"
-    #include "quill/LogMacros.h"
-    #include "quill/Logger.h"
-    #include "quill/sinks/ConsoleSink.h"
-
-    int main()
-    {
-      // Start the backend thread
-      quill::Backend::start();
-
-      // Frontend
-      auto console_sink = quill::Frontend::create_or_get_sink<quill::ConsoleSink>("sink_id_1");
-      quill::Logger* logger = quill::Frontend::create_or_get_logger("root", std::move(console_sink));
-
-      LOG_INFO(logger, "This is a log info example {}", 123);
-    }
+.. literalinclude:: examples/quill_docs_example_basic.cpp
+   :language: cpp
+   :linenos:
 
 In the example above, a console `Sink` is created and passed to a `Logger` with its name set to 'root'.
 

docs/cheat_sheet.rst

@@ -566,3 +566,64 @@ Outputs:
     Order is timestamp=17220432928367021 symbol=AAPL price=220.1 quantity=100
 
     Order [order: timestamp=17220432928367021 symbol=AAPL price=220.1 quantity=100]
+
+Using External fmt Formatter Specializations
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Quill uses a custom namespace, ``fmtquill``, and requires formatter specializations to be defined under the same namespace. However, when an external ``libfmt`` is also used, you can reuse existing ``fmt::formatter`` specializations instead of redefining them.
+
+.. note::
+
+   Ensure that the major version of your external ``libfmt`` matches Quill's internal version to avoid ABI incompatibilities.
+
+If you choose to reuse an existing ``fmt::formatter`` specialization, you can derive from it. However, you must template both ``parse`` and ``format`` to support different ``Context`` types.
+
+.. code:: cpp
+
+    struct User
+    {
+      int id = 1;
+      int age = 32;
+    };
+
+    template <>
+    struct fmt::formatter<User>
+    {
+      template <typename TFormatParseCtx>
+      constexpr auto parse(TFormatParseCtx& ctx) { return ctx.begin(); }
+
+      template <typename TFormatCtx>
+      auto format(::User const& user, TFormatCtx& ctx) const
+      {
+        return fmt::format_to(ctx.out(), "id: {}, age: {}", user.id, user.age);
+      }
+    };
+
+    template <>
+    struct fmtquill::formatter<User> : fmt::formatter<User>
+    {
+    };
+
+    template <>
+    struct quill::Codec<User> : DeferredFormatCodec<User>
+    {
+    };
+
+If the external specialization derives from ``fmt::ostream_formatter``, the above approach won't work because ``parse`` is not templated. In this case, you must directly specialize ``fmtquill::ostream_formatter``.
+
+.. code:: cpp
+
+    template <>
+    struct fmt::formatter<User> : fmt::ostream_formatter
+    {
+    };
+
+    template <>
+    struct fmtquill::formatter<User> : fmtquill::ostream_formatter
+    {
+    };
+
+    template <>
+    struct quill::Codec<User> : DeferredFormatCodec<User>
+    {
+    };

docs/csv_writing.rst

@@ -10,34 +10,9 @@ The :cpp:class:`CsvWriter` class is a utility designed to facilitate asynchronou
 CSV Writing To File
 -------------------
 
-.. code:: cpp
-
-    #include "quill/Backend.h"
-    #include "quill/core/FrontendOptions.h"
-    #include "quill/CsvWriter.h"
-    #include "quill/sinks/ConsoleSink.h"
-    #include "quill/LogMacros.h"
-
-    struct OrderCsvSchema
-    {
-      static constexpr char const* header = "order_id,symbol,quantity,price,side";
-      static constexpr char const* format = "{},{},{},{:.2f},{}";
-    };
-
-    int main()
-    {
-      quill::BackendOptions backend_options;
-      quill::Backend::start(backend_options);
-
-      quill::Logger* logger = quill::Frontend::create_or_get_logger("root", quill::Frontend::create_or_get_sink<quill::ConsoleSink>("sink_id_1"));
-
-      LOG_INFO(logger, "CSV writing example");
-
-      quill::CsvWriter<OrderCsvSchema, quill::FrontendOptions> csv_writter {"orders.csv"};
-      csv_writter.append_row(13212123, "AAPL", 100, 210.32321, "BUY");
-      csv_writter.append_row(132121123, "META", 300, 478.32321, "SELL");
-      csv_writter.append_row(13212123, "AAPL", 120, 210.42321, "BUY");
-    }
+.. literalinclude:: ../examples/csv_writing.cpp
+   :language: cpp
+   :linenos:
 
 Csv output (orders.csv):
 
@@ -50,37 +25,8 @@ Csv output (orders.csv):
 
 CSV Writing To Existing Sink
 ----------------------------
-It is possible to pass an existing `Sink`, or a custom user-created `Sink`, to the CSV file for output.
-
-.. code:: cpp
-
-    #include "quill/Backend.h"
-    #include "quill/CsvWriter.h"
-    #include "quill/LogMacros.h"
-    #include "quill/core/FrontendOptions.h"
-    #include "quill/sinks/ConsoleSink.h"
-
-    struct OrderCsvSchema
-    {
-      static constexpr char const* header = "order_id,symbol,quantity,price,side";
-      static constexpr char const* format = "{},{},{},{:.2f},{}";
-    };
-
-    int main()
-    {
-      quill::BackendOptions backend_options;
-      quill::Backend::start(backend_options);
-
-      quill::Logger* logger = quill::Frontend::create_or_get_logger(
-        "root", quill::Frontend::create_or_get_sink<quill::ConsoleSink>("sink_id_1"));
-
-      LOG_INFO(logger, "CSV writing example");
-
-      std::shared_ptr<quill::Sink> existing_sink = quill::Frontend::get_sink("sink_id_1");
+It is possible to pass an existing `Sink`, or a custom user-created `Sink`, to the CSV file for output. The following example shows how to use the console sink
 
-      // Pass the existing ConsoleSink to the CsvWritter, this will output the csv to console
-      quill::CsvWriter<OrderCsvSchema, quill::FrontendOptions> csv_writer{"orders.csv", existing_sink};
-      csv_writer.append_row(13212123, "AAPL", 100, 210.32321, "BUY");
-      csv_writer.append_row(132121123, "META", 300, 478.32321, "SELL");
-      csv_writer.append_row(13212123, "AAPL", 120, 210.42321, "BUY");
-    }
+.. literalinclude:: examples/quill_docs_example_csv_writer_1.cpp
+   :language: cpp
+   :linenos:

docs/examples.rst

@@ -6,99 +6,13 @@ Examples
 Simple
 ------
 
-.. code:: cpp
-
-    #include "quill/Backend.h"
-    #include "quill/Frontend.h"
-    #include "quill/LogMacros.h"
-    #include "quill/Logger.h"
-    #include "quill/sinks/ConsoleSink.h"
-
-    #include "quill/std/Array.h"
-
-    #include <string>
-    #include <utility>
-
-    int main()
-    {
-      quill::BackendOptions backend_options;
-      quill::Backend::start(backend_options);
-
-      // Frontend
-      auto console_sink = quill::Frontend::create_or_get_sink<quill::ConsoleSink>("sink_id_1");
-      quill::Logger* logger = quill::Frontend::create_or_get_logger("root", std::move(console_sink));
-
-      // Change the LogLevel to print everything
-      logger->set_log_level(quill::LogLevel::TraceL3);
-
-      // A log message with number 123
-      int a = 123;
-      std::string l = "log";
-      LOG_INFO(logger, "A {} message with number {}", l, a);
-
-      // libfmt formatting language is supported 3.14e+00
-      double pi = 3.141592653589793;
-      LOG_INFO(logger, "libfmt formatting language is supported {:.2e}", pi);
-
-      // Logging STD types is supported [1, 2, 3]
-      std::array<int, 3> arr = {1, 2, 3};
-      LOG_INFO(logger, "Logging STD types is supported {}", arr);
-
-      // Logging STD types is supported [arr: [1, 2, 3]]
-      LOGV_INFO(logger, "Logging STD types is supported", arr);
-
-      // A message with two variables [a: 123, b: 3.17]
-      double b = 3.17;
-      LOGV_INFO(logger, "A message with two variables", a, b);
-
-      for (uint32_t i = 0; i < 10; ++i)
-      {
-        // Will only log the message once per second
-        LOG_INFO_LIMIT(std::chrono::seconds{1}, logger, "A {} message with number {}", l, a);
-        LOGV_INFO_LIMIT(std::chrono::seconds{1}, logger, "A message with two variables", a, b);
-      }
-    }
+.. literalinclude:: examples/quill_docs_example_simple.cpp
+   :language: cpp
+   :linenos:
 
 Logging to file
 ---------------
 
-.. code:: cpp
-
-    #include "quill/Backend.h"
-    #include "quill/Frontend.h"
-    #include "quill/LogMacros.h"
-    #include "quill/Logger.h"
-    #include "quill/sinks/FileSink.h"
-
-    #include <utility>
-
-    int main()
-    {
-      // Start the backend thread
-      quill::BackendOptions backend_options;
-      quill::Backend::start(backend_options);
-
-      // Frontend
-      auto file_sink = quill::Frontend::create_or_get_sink<quill::FileSink>(
-        "trivial_logging.log",
-        []()
-        {
-          quill::FileSinkConfig cfg;
-          cfg.set_open_mode('w');
-          cfg.set_filename_append_option(quill::FilenameAppendOption::StartDateTime);
-          return cfg;
-        }(),
-        quill::FileEventNotifier{});
-
-      quill::Logger* logger =
-        quill::Frontend::create_or_get_logger("root", std::move(file_sink),
-                                              quill::PatternFormatterOptions { "%(time) [%(thread_id)] %(short_source_location:<28) "
-                                              "LOG_%(log_level:<9) %(logger:<12) %(message)",
-                                              "%H:%M:%S.%Qns", quill::Timezone::GmtTime });
-
-      // set the log level of the logger to debug (default is info)
-      logger->set_log_level(quill::LogLevel::Debug);
-
-      LOG_INFO(logger, "log something {}", 123);
-      LOG_DEBUG(logger, "something else {}", 456);
-    }
+.. literalinclude:: examples/quill_docs_example_file.cpp
+   :language: cpp
+   :linenos: