improve documentation

odygrd · Feb 15, 2025 · 6e81cca · 6e81cca
1 parent da1150d
commit 6e81cca
Show file tree

Hide file tree

Showing 6 changed files with 52 additions and 28 deletions.
diff --git a/docs/CMakeLists.txt b/docs/CMakeLists.txt
@@ -41,20 +41,26 @@ add_custom_command(OUTPUT ${SPHINX_INDEX_FILE}
         WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
         DEPENDS
         # Other docs files you want to track should go here (or in some variable)
+        ${CMAKE_CURRENT_SOURCE_DIR}/backend_options.rst
+        ${CMAKE_CURRENT_SOURCE_DIR}/backtrace_logging.rst
         ${CMAKE_CURRENT_SOURCE_DIR}/basic_example.rst
-        ${CMAKE_CURRENT_SOURCE_DIR}/logging_macros.rst
-        ${CMAKE_CURRENT_SOURCE_DIR}/sinks.rst
-        ${CMAKE_CURRENT_SOURCE_DIR}/timestamp_types.rst
-        ${CMAKE_CURRENT_SOURCE_DIR}/sink_types.rst
+        ${CMAKE_CURRENT_SOURCE_DIR}/cheat_sheet.rst
+        ${CMAKE_CURRENT_SOURCE_DIR}/csv_writing.rst
         ${CMAKE_CURRENT_SOURCE_DIR}/filters.rst
         ${CMAKE_CURRENT_SOURCE_DIR}/formatters.rst
-        ${CMAKE_CURRENT_SOURCE_DIR}/loggers.rst
-        ${CMAKE_CURRENT_SOURCE_DIR}/backtrace_logging.rst
+        ${CMAKE_CURRENT_SOURCE_DIR}/frontend_options.rst
         ${CMAKE_CURRENT_SOURCE_DIR}/index.rst
-        ${CMAKE_CURRENT_SOURCE_DIR}/users-api.rst
         ${CMAKE_CURRENT_SOURCE_DIR}/installing.rst
-        ${CMAKE_CURRENT_SOURCE_DIR}/examples.rst
+        ${CMAKE_CURRENT_SOURCE_DIR}/json_logging.rst
+        ${CMAKE_CURRENT_SOURCE_DIR}/log_tagging.rst
+        ${CMAKE_CURRENT_SOURCE_DIR}/loggers.rst
+        ${CMAKE_CURRENT_SOURCE_DIR}/logging_macros.rst
         ${CMAKE_CURRENT_SOURCE_DIR}/overview.rst
+        ${CMAKE_CURRENT_SOURCE_DIR}/quick_start.rst
+        ${CMAKE_CURRENT_SOURCE_DIR}/sink_types.rst
+        ${CMAKE_CURRENT_SOURCE_DIR}/sinks.rst
+        ${CMAKE_CURRENT_SOURCE_DIR}/timestamp_types.rst
+        ${CMAKE_CURRENT_SOURCE_DIR}/users-api.rst
         ${CMAKE_CURRENT_SOURCE_DIR}/wide_strings.rst
         ${DOXYGEN_INDEX_FILE}
         MAIN_DEPENDENCY ${SPHINX_SOURCE}/conf.py

diff --git a/docs/examples.rst b/docs/examples.rst
diff --git a/docs/examples/CMakeLists.txt b/docs/examples/CMakeLists.txt
@@ -4,12 +4,12 @@ set(EXAMPLE_TARGETS
         quill_docs_example_backtrace_logging_1
         quill_docs_example_backtrace_logging_2
         quill_docs_example_basic
+        quill_docs_example_console
         quill_docs_example_csv_writer_1
         quill_docs_example_custom_format
         quill_docs_example_file
         quill_docs_example_filter_1
         quill_docs_example_json_logging
-        quill_docs_example_simple
         quill_docs_timestamp_types_1
 )
 

diff --git a/docs/examples/quill_docs_example_simple.cpp → docs/examples/quill_docs_example_console.cpp b/docs/examples/quill_docs_example_simple.cpp → docs/examples/quill_docs_example_console.cpp
diff --git a/docs/index.rst b/docs/index.rst
@@ -17,7 +17,7 @@ Quill is a high-performance asynchronous C++ logging library. It excels in perfo
 
    overview
    installing
-   examples
+   quick_start
    cheat_sheet
 
 .. toctree::

diff --git a/docs/quick_start.rst b/docs/quick_start.rst
@@ -0,0 +1,36 @@
+.. title:: Quick Start
+
+Quick Start
+===========
+
+The library consists of two main components: the frontend and the backend.
+
+The **frontend** captures a copy of the log arguments and metadata from each ``LOG_*`` statement and places them in a thread-local SPSC queue buffer.
+
+The **backend** runs in a separate thread, spawned by the library, asynchronously consuming messages from the frontend, formatting them, and writing them to the configured sinks.
+
+To use the library, you need to start the backend thread in your application. Then, set up one or more output ``Sinks`` and a ``Logger``.
+
+Once the initialization is complete, you only need to include two header files to issue log statements:
+
+- ``#include "quill/LogMacros.h"``
+- ``#include "quill/Logger.h"``
+
+These headers have minimal dependencies, keeping compilation times low.
+
+For even faster compilation, consider building the backend initialization as a static library, as shown in:
+`Recommended Usage Example <https://github.com/odygrd/quill/tree/master/examples/recommended_usage>`_.
+
+Logging to Console
+------------------
+
+.. literalinclude:: examples/quill_docs_example_console.cpp
+   :language: cpp
+   :linenos:
+
+Logging to File
+---------------
+
+.. literalinclude:: examples/quill_docs_example_file.cpp
+   :language: cpp
+   :linenos: