how to debug (or trace) rendering issues

[anb0s]

We are using mkdocs-with-pdf and facing sometimes issues we do not understand. Is it somehow possible to trace or debug the issue? E.g. have some pointers to related files etc.?

Example traceback:

INFO     -  Rendering for PDF.
Traceback (most recent call last):
  File "/usr/local/bin/mkdocs", line 8, in <module>
    sys.exit(cli())
  File "/usr/local/lib/python3.8/site-packages/click/core.py", line 1137, in __call__
    return self.main(*args, **kwargs)
  File "/usr/local/lib/python3.8/site-packages/click/core.py", line 1062, in main
    rv = self.invoke(ctx)
  File "/usr/local/lib/python3.8/site-packages/click/core.py", line 1668, in invoke
    return _process_result(sub_ctx.command.invoke(sub_ctx))
  File "/usr/local/lib/python3.8/site-packages/click/core.py", line 1404, in invoke
    return ctx.invoke(self.callback, **ctx.params)
  File "/usr/local/lib/python3.8/site-packages/click/core.py", line 763, in invoke
    return __callback(*args, **kwargs)
  File "/usr/local/lib/python3.8/site-packages/mkdocs/__main__.py", line 183, in build_command
    build.build(config.load_config(**kwargs), dirty=not clean)
  File "/usr/local/lib/python3.8/site-packages/mkdocs/commands/build.py", line 309, in build
    config['plugins'].run_event('post_build', config=config)
  File "/usr/local/lib/python3.8/site-packages/mkdocs/plugins.py", line 96, in run_event
    result = method(**kwargs)
  File "/usr/local/lib/python3.8/site-packages/mkdocs_with_pdf/plugin.py", line 135, in on_post_build
    self.generator.on_post_build(config, self.config['output_path'])
  File "/usr/local/lib/python3.8/site-packages/mkdocs_with_pdf/generator.py", line 151, in on_post_build
    render = html.render()
  File "/usr/local/lib/python3.8/site-packages/weasyprint/__init__.py", line 172, in render
    return Document._render(
  File "/usr/local/lib/python3.8/site-packages/weasyprint/document.py", line 396, in _render
    context = cls._build_layout_context(
  File "/usr/local/lib/python3.8/site-packages/weasyprint/document.py", line 374, in _build_layout_context
    style_for = get_all_computed_styles(
  File "/usr/local/lib/python3.8/site-packages/weasyprint/css/__init__.py", line 1037, in get_all_computed_styles
    for sheet in find_stylesheets(
  File "/usr/local/lib/python3.8/site-packages/weasyprint/css/__init__.py", line 243, in find_stylesheets
    for wrapper in wrapper_element.query_all('style', 'link'):
  File "/usr/local/lib/python3.8/site-packages/cssselect2/tree.py", line 232, in <genexpr>
    if any(test(element) for test in tests)
  File "/usr/local/lib/python3.8/site-packages/cssselect2/tree.py", line 232, in <genexpr>
    if any(test(element) for test in tests)
  File "<string>", line 1, in <lambda>
  File "/usr/local/lib/python3.8/site-packages/cssselect2/tree.py", line 21, in __get__
    value = self.func(obj)
  File "/usr/local/lib/python3.8/site-packages/cssselect2/tree.py", line 268, in local_name
    namespace_url, local_name = _split_etree_tag(self.etree_element.tag)
  File "/usr/local/lib/python3.8/site-packages/cssselect2/tree.py", line 342, in _split_etree_tag
    assert tag[0] == '{'
AssertionError

[StefanSchroeder]

I have to admit that the Python Tracebacks are pretty intimidating. My steps:

1. Read https://realpython.com/python-traceback/
2. In the mkdocs-configuration for the plugin, activate "debug_html: true"

If all else fails, you could add strategic print/log messages into your code, as Guido intended.

First, you have to identify the file that is provoking the error by systematically replacing your tailored files with boilerplate examples, until the error disappears.

My suspicion without digging deeper into your Trace is that one of your input files has a syntax error. You could use linters/checkers that validate the integrity of all your inputfiles.

For JSON, use jq. For CSS, use http://csslint.net/. I haven't used the latter, it was just the first Google hit.