Skip to content

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).

Console and file logger settings

Both console and file loggers are configured separately and their defaults settings are different.

Privacy disclaimer

pub-debugger plugin do not send any files over the internet, but if you want to use a Zip file as an attachment for an issue submission or share it with anybody, before please make a review of the content of this archive file.

Please remember

It's your data and your responsibility what you are publishing over the internet. This plugin is only giving you the tool that should help, and you cannot blame me (the author of this plugin) for any potential data leaks.

Python logging for MkDocs

Information

This section is for any MkDocs plugin developer.

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.

The best practice for logger naming

Logger name should be built according to given structure:

mkdocs.plugins.[project_name].[directory].[optional_sub_directories].[file_name].

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:

None

Code link

Be aware, that the above screenshot is the most future rich output. The default plugin configuration doesn't enable the code link section (it has to be enabled).

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.

enabled

Controls if console log will be replaced with a new, richer format.

log_level

Set the log level.

show_code_link

Controls if the code link part is visible in the log message (useful for IDE like PyCharm).

show_logger_name

Controls if the logger name part is visible in the log message (useful when you want to filter some of the messages or plugins).

show_entry_time

Controls if the time entry part is visible in the log message.

show_deprecation_warnings

Controls if deprecation warnings will be visible in the log message.

entry_time_format

Defines time format.

filter_logger_names

Define a list of logger names that will be filtered out of the log messages.

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.

enabled

Controls if log file will be created.

log_level

Set the log level.

log_format

Defines format of the message that will be put into the log file.

remove_old_files

Controls if previously created log files will be removed while creating a new one.

filter_logger_names

Define a list of logger names that will be filtered out of the log messages.

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.

enabled

Controls if zip file will be created.

remove_old_files

Controls if previously created zip files will be removed while creating a new one.

add_pip_freeze

Controls if zip file will contain a requirements.txt file with a list of Python libraries (it's helpful with issue reproduction when you want to report one).