Setting up a debugger plugin¶

Introduction¶

Each good developer knows, how important is the possibility to read proper logs from running application when there is some issue. MkDocs by default produces some logs while documentation is being built or while the built-in server is running. Because the whole MkDocs is written using the Python programming language, there is a possibility to configure a debugger in tools like PyCharm or VsCode. But how to handle logging when you are just a user and do not have a needed knowledge and just want to submit an issue because you have found some problem? To help with debugging by logging and producing additional files that can be attached to the issue submission, Publisher for MkDocs contains a pub-debugger plugin. It's built with 3 main modules:

• console logger that allows to change the output produced to the console,
• file logger that allows to produce the log file,
• Zip file generator that allows to produce a Zip file with log file produced by previous module and some additional files like mkdocs.yml and Python package files like requirements.txt or pyproject.tml and poetry.lock (depends on type of Python package manager you have used).

Python logging for MkDocs¶

Because MkDocs is written in Python, whenever someone wants to write a new plugin and see some information during documentation build, he has to use a logging library. The usual use of this library is to do something like this:

import logging

logger = logging.get_logger(__name__)
logger.info("Some output")

The biggest problem with this approach is that __name__ becomes a file name (without extension), so the logger for the above example is new_mkdocs_plugin. Since all loggers inside MkDocs have a name corresponding to a directory structure that leads to the file where logger is used, any MkDocs plugin developer should do the same.

Let's take a look at one of the files from this project repository.

import logging

...

log = logging.getLogger("mkdocs.plugins.publisher.minifier.minifiers")

.
└─ mkdocs_publisher/
  └─ minifier/
    └─ minifiers.py

Configuration¶

To enable the built-in debugger plugin, the following lines have to be added to mkdocs.yml file:

plugins:
  - pub-debugger

Console logging¶

By default, MkDocs produces a console log, that contains only basic information like log level and log message. In normal usage, this information is quite sufficient, but when any problem with a build process occurs, it's quite hard to find a specific line where the problem has happened. Because of that, pub-debugger allows you to override the default console logger with one that contains more information. Below you can find what does it look like:

plugins:
  - pub-debugger:
      console_log:
        enabled: true
        log_level: INFO
        show_code_link: false
        show_logger_name: true
        show_entry_time: true
        show_deprecation_warnings: false
        entry_time_format: "%H:%M:%S.%f"
        filter_logger_names: []

Above you can find all possible settings with their default values. You don't have to provide them. Just use them if you want to change some settings. The description of the meaning of given setting, you can find below.

File logging¶

plugins:
  - pub-debugger:
      file_log:
        enabled: true
        log_level: DEBUG
        log_format: "[%(created).14s][%(levelname)-5.5s][%(project_path)s:%(lineno)d] %(message)s"
        remove_old_files: true
        filter_logger_names: []

Above you can find all possible settings with their default values. You don't have to provide them. Just use them if you want to change some settings. The description of the meaning of given setting, you can find below.

Zip file generation¶

plugins:
  - pub-debugger:
      zip_log:
        enabled: true
        remove_old_files: true
        add_pip_freeze: true

Above you can find all possible settings with their default values. You don't have to provide them. Just use them if you want to change some settings. The description of the meaning of given setting, you can find below.

Backlinks: