📝 Update docs

6i-software · Dec 13, 2024 · 7dea4c3 · 7dea4c3
1 parent 6a50e2b
commit 7dea4c3
Show file tree

Hide file tree

Showing 16 changed files with 325 additions and 10 deletions.
diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml
@@ -4,7 +4,7 @@ site_name: VBA Monologger
 site_url: https://github.com/6i-software/vba-monologger/
 site_author: 2o1oo <[email protected]>
 site_description: >-
-  Official site documentation of VBA Monologger, an advanced and flexible logging solution for VBA ecosystem.
+  VBA Monologger is an advanced and flexible logging solution for VBA (<i>Visual Basic for Applications</i>) ecosystem.
 copyright: Copyright &copy; 2024, 6i-software - 2o1oo
 
 repo_name: 6i-software/vba-monologger
@@ -15,9 +15,8 @@ docs_dir: src
 theme:
   language: en
   name: material
+  custom_dir: overrides
   features:
-    - content.action.edit
-    - content.action.view
     - content.code.annotate
     - content.code.copy
     - content.tabs.link
@@ -66,11 +65,14 @@ plugins:
 
 extra:
   generator: false
+  analytics:
+    provider: google
+    property: G-LT06F6P562
   social:
     - icon: fontawesome/brands/github
       link: https://github.com/v20100v
     - icon: fontawesome/regular/envelope
-      link: "mailto:[email protected]?subject=[VBA%20Monologger]"
+      link: "mailto:[email protected]?subject=[6i-VBA%20Monologger]"
       label: "Contactez-nous"
   consent:
     title: Cookie consent
@@ -140,8 +142,9 @@ nav:
   - Welcome: index.md
   - Getting started:
       - getting-started/index.md
-      - Installation: installation.md
-      - Creating your logger: creating-your-logger.md
+      - Installation: getting-started/installation.md
+      - Basic usages: getting-started/basic-usages.md
+      - Creating your logger: getting-started/creating-your-logger.md
   - Under the hood:
     - under-the-hood/index.md
     - Log severity levels: under-the-hood/log-severity-levels.md

diff --git a/docs/overrides/welcome.html b/docs/overrides/welcome.html
@@ -0,0 +1,137 @@
+{% extends "base.html" %}
+
+{% block header %}
+
+{% set class = "md-header" %}
+{% if "navigation.tabs.sticky" in features %}
+    {% set class = class ~ " md-header--shadow md-header--lifted" %}
+{% elif "navigation.tabs" not in features %}
+    {% set class = class ~ " md-header--shadow" %}
+{% endif %}
+<header class="{{ class }}" data-md-component="header">
+    <nav class="md-header__inner md-grid" aria-label="{{ lang.t('header') }}">
+        <a href="{{ config.extra.homepage | d(nav.homepage.url, true) | url }}" title="{{ config.site_name | e }}" class="md-header__button md-logo" aria-label="{{ config.site_name }}" data-md-component="logo">
+            {% include "partials/logo.html" %}
+        </a>
+        <label class="md-header__button md-icon" for="__drawer">
+            {% set icon = config.theme.icon.menu or "material/menu" %}
+            {% include ".icons/" ~ icon ~ ".svg" %}
+        </label>        
+        {% if config.theme.palette %}
+            {% if not config.theme.palette is mapping %}
+                {% include "partials/palette.html" %}
+            {% endif %}
+        {% endif %}
+
+        <div class="md-header__title" data-md-component="header-title">
+            <div class="md-header__ellipsis">
+                <div class="md-header__topic">
+                    <span class="md-ellipsis">
+                        {{ config.site_name }}
+                    </span>
+                </div>
+            </div>
+        </div>        
+
+        {% if not config.theme.palette is mapping %}
+            {% include "partials/javascripts/palette.html" %}
+        {% endif %}
+    </nav>
+</header>
+
+{% endblock %}
+
+
+
+<!-- Render landing page under block tabs -->
+{% block tabs %}
+
+<!-- Additional styles for landing page -->
+<style>
+
+    /* Application header should be static for the landing page */
+    .md-header {
+        position: initial;
+    }
+
+    /* Remove spacing, as we cannot hide it completely */
+    .md-main__inner {
+        margin: 0;
+    }
+
+    /* Hide main content for now */
+    .md-content {
+        display: none;
+    }
+
+    /* Hide table of contents */
+    @media screen and (min-width: 60em) {
+        .md-sidebar--secondary {
+            display: none;
+        }
+    }
+
+    /* Hide navigation */
+    @media screen and (min-width: 76.25em) {
+        .md-sidebar--primary {
+            display: none;
+        }
+    }
+
+    .custom-hero {
+        margin-top:10%;
+        margin-left:6%;
+        margin-right:6%;
+    }
+
+    .custom-hero-content p {
+        max-width: 400px;
+    }
+
+    .decoration {
+        background: linear-gradient(
+                to bottom,
+                color-mix(in srgb, var(--md-primary-fg-color) 85%, white),
+                color-mix(in srgb, var(--md-primary-fg-color) 0%, transparent)
+        );
+        height: 20vh;
+    }
+</style>
+
+<!-- Hero for landing page -->
+
+
+<section class="custom-landing-container">
+
+    <div class="decoration"></div>
+
+    <div class="md-grid md-typeset">
+        <div class="custom-hero">
+            <!-- Hero image -->
+            <div class="custom-hero-image">
+                <!-- <img src="assets/images/hero.png" alt="" width="1659" height="1200" draggable="false"> -->
+            </div>
+
+            <!-- Hero content -->
+            <div class="custom-hero-content">
+                <h1>Log smarter, debug faster in VBA</h1>
+                <p>{{ config.site_description }} Set up in two minutes.</p>
+                <a href="{{ 'getting-started/' | url }}" title="Set up in two minutes!" class="md-button md-button--primary">
+                    Get started
+                </a>
+                <a href="{{ 'under-the-hood/' | url }}" title="To understand and learn what's happening with each compontents of this library" class="md-button">
+                    Learn more
+                </a>
+            </div>
+        </div>
+    </div>
+</section>
+{% endblock %}
+
+<!-- Content -->
+{% block content %}{% endblock %}
+
+<!-- Application footer -->
+{% block footer %}
+{{ super() }}
+{% endblock %}
diff --git a/docs/src/assets/VBAMonologger-output-VBAConsole.png b/docs/src/assets/VBAMonologger-output-VBAConsole.png
diff --git a/docs/src/assets/VBAMonologger-output-WindowsConsole.png b/docs/src/assets/VBAMonologger-output-WindowsConsole.png
diff --git a/docs/src/assets/VBAMonologger-output-placeholders.png b/docs/src/assets/VBAMonologger-output-placeholders.png
diff --git a/docs/src/assets/css/extra-customize.css b/docs/src/assets/css/extra-customize.css
@@ -4,8 +4,20 @@ pre code {
     word-wrap: break-word;
 }
 
+.md-header {
+    background: linear-gradient(
+            to bottom,
+            color-mix(in srgb, var(--md-primary-fg-color) 100%, white),
+            color-mix(in srgb, var(--md-primary-fg-color) 85%, white)
+    );    
+}
+
 .md-tabs {
-    background-color: color-mix(in srgb, var(--md-primary-fg-color) 80%, white);  /* Mixe la couleur avec du blanc pour l'éclaircir */
+    background: linear-gradient(
+            to bottom,
+            color-mix(in srgb, var(--md-primary-fg-color) 85%, white),
+            color-mix(in srgb, var(--md-primary-fg-color) 70%, white)
+    );
 }
 
 .md-footer-meta {

diff --git a/docs/src/getting-started/VBAMonologger-output-VBAConsole.png b/docs/src/getting-started/VBAMonologger-output-VBAConsole.png
diff --git a/docs/src/getting-started/VBAMonologger-output-WindowsConsole.png b/docs/src/getting-started/VBAMonologger-output-WindowsConsole.png
diff --git a/docs/src/getting-started/basic-usages.md b/docs/src/getting-started/basic-usages.md
@@ -0,0 +1,136 @@
+## Severity levels
+
+The severity levels indicate the severity of each event, from the most trivial to the most catastrophic, and allow administrators or developers to filter messages based on their importance.
+
+**VBA Monologger** manages 8 standard severity levels to classify the importance of log messages, following the [PSR-3](https://www.php-fig.org/psr/psr-3/) standard, which is itself based on RFC 5424, the standard defined by the IETF (*Internet Engineering Task Force*) to specify the format of messages for the Syslog protocol, which is used for transmitting logs over IP networks.
+
+| Log level   | Description                                                                                                                                                                                                                               |
+|-------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `EMERGENCY` | Indicates a very critical situation that requires immediate attention. (System crash, data corruption)                                                                                                                                    |
+| `ALERT`     | Signals an alert condition. (Critical disk space running out)                                                                                                                                                                             |
+| `CRITICAL`  | Indicates a serious error. (Database connection failure, server downtime)                                                                                                                                                                 |
+| `ERROR`     | Represents an error in the system. (Failed to save user data, unexpected exception)                                                                                                                                                       |
+| `WARNING`   | A warning about a potential problem. (Use a deprecated function used, low memory warning)                                                                                                                                                 |
+| `NOTICE`    | Important notifications that are not urgent. (User login successful, configuration change detected)                                                                                                                                       |
+| `INFO`      | General information about the normal operation. (System startup, data processed successfully)                                                                                                                                             |
+| `DEBUG`     | Detailed information for debugging. (Variable values during loop iteration, query execution details). Notes, that the '**debug**' method exposes presents in PSR-3 is rename into '**trace**' in order to be compatible in VBA ecosystem. |
+
+Each logger must implement hte interface `LoggerInterface`. ' This interface is (*supposed to be*) designed according to the PSR-3 standard (see: https://www.php-fig.org/psr/psr-3/), and exposed this methods:
+
+```vbscript
+' Logs message for each severity levels
+Logger.trace "Authentication function call for user 'Bob Morane'." 
+Logger.info "User 'UltraVomit' has logged in successfully."
+Logger.notice "Process completed successfully with minor issues."
+Logger.warning "'Beetlejuice' should not be called more than 3 times."
+Logger.error "An error occurred with the user 'DRZCFOS2'."
+Logger.critical "System is in an unstable state."
+Logger.alert "Action required: unable to generate the dashboard."
+Logger.emergency "A critical failure occurred in the application."
+```
+
+
+
+## Create default logger with factory
+
+### Log output to VBA Console
+
+To create a logger that output logs into the VBA console, we use the factory `VBAMonologger.Factory`, as shown below. 
+
+This logger is configured by default with the handler `VBAMonologger.Handler.HandlerConsoleVBA`, which uses the default line formatter: `VBAMonologger.Formatter.FormatterLine`. By default, this logger also loads the pre-processors placeholders: `VBAMonologger.Processor.ProcessorPlaceholders`, allowing the use of placeholders in log messages that will be replaced with values provided in the log record context.
+
+```vbscript
+Public Sub howto_use_loggerConsoleVBA()
+    ' Create a logger instance for output log into VBA console
+    Dim Logger As VBAMonologger.LoggerInterface
+    Set Logger = VBAMonologger.Factory.createLoggerConsoleVBA("App")
+
+    ' Logs message for each severity levels
+    Logger.trace "Authentication function call for user 'Bob Morane'." 
+    Logger.info "User 'UltraVomit' has logged in successfully."
+    Logger.notice "Process completed successfully with minor issues."
+    Logger.warning "'Beetlejuice' should not be called more than 3 times."
+    Logger.error "An error occurred with the user 'DRZCFOS2'."
+    Logger.critical "System is in an unstable state."
+    Logger.alert "Action required: unable to generate the dashboard."
+    Logger.emergency "A critical failure occurred in the application."
+End Sub
+```
+
+You can see result in the **VBA console** (a.k.a. **Excel's Immediate Windows**).
+
+![VBAMonologger-output-VBAConsole.png](VBAMonologger-output-VBAConsole.png)
+
+> Note: If the console is not visible in Excel Visual basidc IDE, go to the menu and select *View > Immediate Window*. Alternatively, you can press <kbd>Ctrl</kbd> + <kbd>G</kbd> to quickly open it.
+
+
+### Log output to Windows Console
+
+The factory also provides a logger for Windows console (*cmd.exe*). 
+
+This logger handles log messages by streaming them to the Windows console using an HTTP-based client/server architecture. The client sends log entries as HTTP requests to the server, and the server processes these requests, displaying the log messages directly in the console output. By default, this logger features a formatter that supports ANSI colors (`VBAMonologger.Formatter.FormatterANSIcoloredLine`). It also includes the *placeholders* pre-processors.
+
+```vbscript
+Public Sub howto_use_loggerConsole()
+    Dim Logger As VBAMonologger.LoggerInterface
+    Set Logger = VBAMonologger.Factory.createLoggerConsole("App")
+
+    Logger.trace "Authentication function call for user 'Bob Morane'." 
+    (...)
+End Sub    
+```
+
+When you execute this code, it launches a `cmd.exe`, and you can view the results in it.
+
+![VBAMonologger-output-WindowsConsole.png](VBAMonologger-output-WindowsConsole.png)
+
+### Log output to file
+
+You can send logs into a file with the default logger file.
+
+
+By default, this logger writes logs to the `./var/log/logfile_xxxx-yy-zz.log` file, relative to the path of the workbook. You can change the name and the folder of the file into the configuration of `VBAMonologger.Handler.HandlerFile`. To ensure compatibility with special and multilingual characters in this Handler, the UTF-8 encoding is preferred.
+
+```vbscript
+Public Sub howto_use_loggerConsoleVBA()
+    Dim Logger As VBAMonologger.LoggerInterface
+    Set Logger = VBAMonologger.Factory.createLoggerFile("App")
+
+    ' Logs message for each severity levels
+    Logger.trace "Authentication function call for user 'Bob Morane'."
+    (...)
+End Sub
+```
+
+
+## Use placeholders with context data
+
+By default, all loggers create with the factory includes the pre-processors placeholders (`VBAMonologger.Processor.ProcessorPlaceholders`). You don't need to reference it; it's already done!
+
+
+It is used to dynamically insert specific contextual data into logging messages, allowing for more detailed and contextualized log records. You can choose to display (or not) the context data, either on a single line or across multiple lines, formatted as pretty JSON with whitespace.
+
+```vbscript 
+Public Sub howto_use_placeholders()
+    Dim Logger As VBAMonologger.LoggerInterface
+    Set Logger = VBAMonologger.Factory.createLoggerConsoleVBA("App")
+
+    ' Create a context dictionary
+    Dim context As Object: Set context = CreateObject("Scripting.Dictionary")
+    context.Add "UserName", "Bob Morane"
+    context.Add "UserID", 342527
+
+    ' Use placeholders into log message
+    Logger.trace "Authentication function call for user '{UserName}' with id '{UserID}'.", context
+End Sub
+```
+
+Result in VBA console:
+
+```
+[2024/12/13 16:19:48] App.DEBUG: Authentication function call for user 'Bob Morane' with id '342527'. | context: {"UserName":"Bob Morane","UserID":342527}
+```
+
+
+
+
diff --git a/docs/mkdocs.md → ...getting-started/creating-custom-logger.md b/docs/mkdocs.md → ...getting-started/creating-custom-logger.md
diff --git a/docs/src/getting-started/excel_developer_tab.png b/docs/src/getting-started/excel_developer_tab.png
diff --git a/docs/src/getting-started/excel_reference_vbamonologger.png b/docs/src/getting-started/excel_reference_vbamonologger.png
diff --git a/docs/src/getting-started/index.md b/docs/src/getting-started/index.md
@@ -5,5 +5,10 @@ hide:
 
 # Getting started
 
-## Installation
+## Preamble
+
+VBA provides developers with the ability to automate tasks, interact with the features of
+Microsoft Office applications, and even create applications with a graphical user interface (`Userform`). However, compared to other development ecosystems, VBA only offers a rudimentary logging solution, limited to the `Debug.Print` function, which writes to the Excel console (a.k.a. the Excel immediate window).
+
+The *VBA Monologger* library project was born out of the need for a more advanced and flexible logging solution in the VBA ecosystem. It is (heavily) inspired by the PSR-3 standard in the PHP ecosystem and its most recognized implementation, the Monolog library. The goal of this library is to provide similar features and capabilities, particularly by offering a modular architecture that can easily adapt to different use cases. The main idea is for each developer to easily configure and customize their own logging system according to their needs.
 
diff --git a/docs/src/getting-started/installation.md b/docs/src/getting-started/installation.md
@@ -0,0 +1,21 @@
+## Installation
+
+1. Download the VBA Monologger Excel Add-in (.xlam file) to your computer.
+
+    [6i_VBA-Monologger.xlam](https://github.com/6i-software/vba-monologger/raw/refs/heads/main/src/6i_VBA-Monologger.xlam)
+
+    <small>*Hash SHA1: 46E0FF01DE2A81254375BCF0B5C9BB97C4E53E35*</small>
+
+
+
+2. Put this xlam file into a folder trusted by Excel. Microsoft requires that the xlam file's location be set as a *Trusted Location* for the add-in to function properly. To set this up, go to: *File > Options > Trust Center > Trust Center Settings > Trusted Locations > Add New Location*.
+
+3. Make sur the Developper tab is visible in Excel. By default, the Developer Ribbon is hidden; to enable it, go to *File > Options > Customize Ribbon*, then check the *Developer* box under the Main Tabs section and validate it.
+   <br/>
+   ![excel_developer_tab.png](excel_developer_tab.png)
+
+4. And finally, add the .xlam file as a reference in your VBA project through *Tools > References* in the VBA editor.
+    <br/>
+    ![excel_reference_vbamonologger.png](excel_reference_vbamonologger.png)
+
+That's it. Time to code with it!
diff --git a/docs/src/index.md b/docs/src/index.md
@@ -1,11 +1,12 @@
 ---
+template: welcome.html
 title: VBA Monologger
 social:
   cards_layout_options:
-    title: VBA Monologger documentation, an advanced and flexible logging solution for VBA.
+    title: Documentation of VBA Monologger, an advanced and flexible logging solution in VBA.
 hide:
   - footer
   - feedback
 ---
 
-VBA Monologger is an advanced and flexible logging solution for VBA (*Visual Basic for Applications*) ecosystem. It is largely inspired by the [Monolog](https://github.com/Seldaek/monolog) library in PHP, which itself is inspired by the [Logbook](https://logbook.readthedocs.io/en/stable/) library in Python.
+It is largely inspired by the [Monolog](https://github.com/Seldaek/monolog) library in PHP, which itself is inspired by the [Logbook](https://logbook.readthedocs.io/en/stable/) library in Python.
diff --git a/examples/example.xlsm b/examples/example.xlsm