search

JakubAndrysek / MkDoxy

đź“– Automatically generates API documentation for your project based on Doxygen comments and code snippets in your markdown files.
https://mkdoxy.kubaandrysek.cz/
MIT License
60 stars 16 forks source link

Mkdocs throws Python exception #59

Closed geissdoerfer closed 11 months ago

geissdoerfer commented 1 year ago

Hi there,

trying to build the demo project throws an exception on my system. I've seen your builds are passing on Python 3.11 and it seems the exception is thrown before doxygen is actually called, so newer doxygen version doesn't seem to be the problem.

My system:

Arch Linux x86_64 Python 3.11.3 Doxygen 1.9.7

INFO     -  Cleaning site directory
INFO     -  Building documentation to directory: /tmp/MkDoxy-demo/site
INFO     -  Start plugin MkDoxy
INFO     -  -> Start project 'esp'
INFO     -    -> generating Doxygen filese
INFO     -  Overwriting template 'annotated' with custom template.
INFO     -  -> Start project 'animal'
INFO     -  -> Start project 'stm'
Traceback (most recent call last):
  File "/tmp/MkDoxy-demo/venv/bin/mkdocs", line 8, in <module>
    sys.exit(cli())
             ^^^^^
  File "/tmp/MkDoxy-demo/venv/lib/python3.11/site-packages/click/core.py", line 1130, in __call__
    return self.main(*args, **kwargs)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/tmp/MkDoxy-demo/venv/lib/python3.11/site-packages/click/core.py", line 1055, in main
    rv = self.invoke(ctx)
         ^^^^^^^^^^^^^^^^
  File "/tmp/MkDoxy-demo/venv/lib/python3.11/site-packages/click/core.py", line 1657, in invoke
    return _process_result(sub_ctx.command.invoke(sub_ctx))
                           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/tmp/MkDoxy-demo/venv/lib/python3.11/site-packages/click/core.py", line 1404, in invoke
    return ctx.invoke(self.callback, **ctx.params)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/tmp/MkDoxy-demo/venv/lib/python3.11/site-packages/click/core.py", line 760, in invoke
    return __callback(*args, **kwargs)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/tmp/MkDoxy-demo/venv/lib/python3.11/site-packages/mkdocs/__main__.py", line 250, in build_command
    build.build(cfg, dirty=not clean)
  File "/tmp/MkDoxy-demo/venv/lib/python3.11/site-packages/mkdocs/commands/build.py", line 297, in build
    files = config.plugins.run_event('files', files, config=config)
            ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/tmp/MkDoxy-demo/venv/lib/python3.11/site-packages/mkdocs/plugins.py", line 520, in run_event
    result = method(item, **kwargs)
             ^^^^^^^^^^^^^^^^^^^^^^
  File "/tmp/MkDoxy-demo/venv/lib/python3.11/site-packages/mkdoxy/plugin.py", line 111, in on_files
    self.doxygen[projectName] = Doxygen(doxygenRun.path, parser=parser, cache=cache, debug=self.debug)
                                ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/tmp/MkDoxy-demo/venv/lib/python3.11/site-packages/mkdoxy/doxygen.py", line 90, in __init__
    self._recursive_sort(self.files)
  File "/tmp/MkDoxy-demo/venv/lib/python3.11/site-packages/mkdoxy/doxygen.py", line 104, in _recursive_sort
    self._recursive_sort(child)
  File "/tmp/MkDoxy-demo/venv/lib/python3.11/site-packages/mkdoxy/doxygen.py", line 104, in _recursive_sort
    self._recursive_sort(child)
  File "/tmp/MkDoxy-demo/venv/lib/python3.11/site-packages/mkdoxy/doxygen.py", line 104, in _recursive_sort
    self._recursive_sort(child)
  [Previous line repeated 1 more time]
  File "/tmp/MkDoxy-demo/venv/lib/python3.11/site-packages/mkdoxy/doxygen.py", line 102, in _recursive_sort
    node.sort_children()
  File "/tmp/MkDoxy-demo/venv/lib/python3.11/site-packages/mkdoxy/node.py", line 84, in sort_children
    self._children.sort(key=lambda x: x._name, reverse=False)
TypeError: '<' not supported between instances of 'NoneType' and 'str'

Any ideas?

geissdoerfer commented 1 year ago

Hi, the problem persists in 1.1.2. I suggest you re-open the issue.

JakubAndrysek commented 1 year ago

Hi, I am trying to figure out your issue. All of my tests are successfully passing.

Do you have latest versions of all depending libraries?

geissdoerfer commented 1 year ago

Thanks for looking into this! I just installed into a fresh virtualenv, so everything should be up to date. Here's the output of pip freeze:

certifi==2023.5.7
charset-normalizer==3.1.0
click==8.1.3
colorama==0.4.6
ghp-import==2.1.0
idna==3.4
Jinja2==3.1.2
Markdown==3.3.7
MarkupSafe==2.1.3
mergedeep==1.3.4
mkdocs==1.4.3
mkdocs-material==9.1.18
mkdocs-material-extensions==1.1.1
mkdocs-open-in-new-tab==1.0.2
mkdoxy==1.1.2
packaging==23.1
path==16.6.0
pathlib==1.0.1
Pygments==2.15.1
pymdown-extensions==10.0.1
python-dateutil==2.8.2
PyYAML==6.0
pyyaml_env_tag==0.1
regex==2023.6.3
requests==2.31.0
ruamel.yaml==0.17.32
ruamel.yaml.clib==0.2.7
six==1.16.0
urllib3==2.0.3
watchdog==3.0.0
JakubAndrysek commented 1 year ago

Could you please show the recent error message.

geissdoerfer commented 1 year ago

Sure:

DEBUG    -  Loading configuration file: /tmp/MkDoxy-demo/mkdocs.yml
DEBUG    -  Loaded theme configuration for 'material' from '/tmp/MkDoxy-demo/venv/lib/python3.11/site-packages/material/mkdocs_theme.yml': {'language': 'en', 'direction': None,
            'features': [], 'font': {'text': 'Roboto', 'code': 'Roboto Mono'}, 'icon': None, 'favicon': 'assets/images/favicon.png', 'static_templates': ['404.html']}
DEBUG    -  Config value 'config_file_path' = '/tmp/MkDoxy-demo/mkdocs.yml'
DEBUG    -  Config value 'site_name' = 'MkDoxy Demo'
DEBUG    -  Config value 'nav' = [{'Home': 'README.md'}, 'useage.md', {'API Demo': ['api/index.md', {'ESP-32': ['esp/index.md', {'Links': 'esp/links.md'}, {'Classes': [{'Class
            List': 'esp/annotated.md'}, {'Class Index': 'esp/classes.md'}, {'Class Hierarchy': 'esp/hierarchy.md'}, {'Class Members': 'esp/class_members.md'}, {'Class Member
            Functions': 'esp/class_member_functions.md'}, {'Class Member Variables': 'esp/class_member_variables.md'}, {'Class Member Typedefs': 'esp/class_member_typedefs.md'},
            {'Class Member Enumerations': 'esp/class_member_enums.md'}]}, {'Namespaces': [{'Namespace List': 'esp/namespaces.md'}, {'Namespace Members': 'esp/namespace_members.md'},
            {'Namespace Member Functions': 'esp/namespace_member_functions.md'}, {'Namespace Member Variables': 'esp/namespace_member_variables.md'}, {'Namespace Member Typedefs':
            'esp/namespace_member_typedefs.md'}, {'Namespace Member Enumerations': 'esp/namespace_member_enums.md'}]}, {'Functions': 'esp/functions.md'}, {'Variables':
            'esp/variables.md'}, {'Macros': 'esp/macros.md'}, {'Files': 'esp/files.md'}]}, {'STM-32': ['stm32/index.md', {'Links': 'stm/links.md'}, {'Classes': [{'Class List':
            'stm/annotated.md'}, {'Class Index': 'stm/classes.md'}, {'Class Hierarchy': 'stm/hierarchy.md'}, {'Class Members': 'stm/class_members.md'}, {'Class Member Functions':
            'stm/class_member_functions.md'}, {'Class Member Variables': 'stm/class_member_variables.md'}, {'Class Member Typedefs': 'stm/class_member_typedefs.md'}, {'Class Member
            Enumerations': 'stm/class_member_enums.md'}]}, {'Namespaces': [{'Namespace List': 'stm/namespaces.md'}, {'Namespace Members': 'stm/namespace_members.md'}, {'Namespace
            Member Functions': 'stm/namespace_member_functions.md'}, {'Namespace Member Variables': 'stm/namespace_member_variables.md'}, {'Namespace Member Typedefs':
            'stm/namespace_member_typedefs.md'}, {'Namespace Member Enumerations': 'stm/namespace_member_enums.md'}]}, {'Functions': 'stm/functions.md'}, {'Variables':
            'stm/variables.md'}, {'Macros': 'stm/macros.md'}, {'Files': 'stm/files.md'}]}, {'Animal': ['animal/index.md', {'Links': 'animal/links.md'}, {'Classes': [{'Class List':
            'animal/annotated.md'}, {'Class Index': 'animal/classes.md'}, {'Class Hierarchy': 'animal/hierarchy.md'}, {'Class Members': 'animal/class_members.md'}, {'Class Member
            Functions': 'animal/class_member_functions.md'}, {'Class Member Variables': 'animal/class_member_variables.md'}, {'Class Member Typedefs':
            'animal/class_member_typedefs.md'}, {'Class Member Enumerations': 'animal/class_member_enums.md'}]}, {'Namespaces': [{'Namespace List': 'animal/namespaces.md'},
            {'Namespace Members': 'animal/namespace_members.md'}, {'Namespace Member Functions': 'animal/namespace_member_functions.md'}, {'Namespace Member Variables':
            'animal/namespace_member_variables.md'}, {'Namespace Member Typedefs': 'animal/namespace_member_typedefs.md'}, {'Namespace Member Enumerations':
            'animal/namespace_member_enums.md'}]}, {'Functions': 'animal/functions.md'}, {'Variables': 'animal/variables.md'}, {'Macros': 'animal/macros.md'}, {'Files':
            'animal/files.md'}]}, {'Jaculus': ['jaculus/index.md', {'Links': 'jaculus/links.md'}, {'Classes': [{'Class List': 'jaculus/annotated.md'}, {'Class Index':
            'jaculus/classes.md'}, {'Class Hierarchy': 'jaculus/hierarchy.md'}, {'Class Members': 'jaculus/class_members.md'}, {'Class Member Functions':
            'jaculus/class_member_functions.md'}, {'Class Member Variables': 'jaculus/class_member_variables.md'}, {'Class Member Typedefs': 'jaculus/class_member_typedefs.md'},
            {'Class Member Enumerations': 'jaculus/class_member_enums.md'}]}, {'Namespaces': [{'Namespace List': 'jaculus/namespaces.md'}, {'Namespace Members':
            'jaculus/namespace_members.md'}, {'Namespace Member Functions': 'jaculus/namespace_member_functions.md'}, {'Namespace Member Variables':
            'jaculus/namespace_member_variables.md'}, {'Namespace Member Typedefs': 'jaculus/namespace_member_typedefs.md'}, {'Namespace Member Enumerations':
            'jaculus/namespace_member_enums.md'}]}, {'Functions': 'jaculus/functions.md'}, {'Variables': 'jaculus/variables.md'}, {'Macros': 'jaculus/macros.md'}, {'Files':
            'jaculus/files.md'}]}]}]
DEBUG    -  Config value 'pages' = None
DEBUG    -  Config value 'site_url' = 'https://mkdoxy-demo.kubaandrysek.cz/'
DEBUG    -  Config value 'site_description' = 'This is a demo of MkDoxy, a tool for generating Doxygen documentation from Markdown files.'
DEBUG    -  Config value 'site_author' = 'Jakub Andrýsek'
DEBUG    -  Config value 'theme' = Theme(name='material', dirs=['/tmp/MkDoxy-demo/venv/lib/python3.11/site-packages/material',
            '/tmp/MkDoxy-demo/venv/lib/python3.11/site-packages/mkdocs/templates'], static_templates=['sitemap.xml', '404.html'], name='material', locale=Locale('en'),
            language='en', direction=None, features=['navigation.tabs', 'navigation.indexes', 'navigation.top', 'navigation.instant', 'navigation.tracking'], font={'text': 'Roboto',
            'code': 'Roboto Mono'}, icon={'repo': 'fontawesome/brands/github'}, favicon='assets/logo.png', logo='assets/logo.png', palette=[{'media': '(prefers-color-scheme: dark)',
            'scheme': 'slate', 'primary': 'amber', 'accent': 'amber', 'toggle': {'icon': 'material/brightness-4', 'name': 'Switch to light mode'}}, {'media': '(prefers-color-scheme:
            light)', 'scheme': 'default', 'primary': 'amber', 'accent': 'amber', 'toggle': {'icon': 'material/brightness-7', 'name': 'Switch to dark mode'}}])
DEBUG    -  Config value 'docs_dir' = '/tmp/MkDoxy-demo/docs'
DEBUG    -  Config value 'site_dir' = '/tmp/MkDoxy-demo/site'
DEBUG    -  Config value 'copyright' = 'Copyright © 2023 Jakub Andrýsek'
DEBUG    -  Config value 'google_analytics' = None
DEBUG    -  Config value 'dev_addr' = _IpAddressValue(host='127.0.0.1', port=8000)
DEBUG    -  Config value 'use_directory_urls' = True
DEBUG    -  Config value 'repo_url' = 'https://github.com/JakubAndrysek/MkDoxy-demo'
DEBUG    -  Config value 'repo_name' = 'JakubAndrysek/MkDoxy-demo'
DEBUG    -  Config value 'edit_uri_template' = None
DEBUG    -  Config value 'edit_uri' = 'edit/master/docs/'
DEBUG    -  Config value 'extra_css' = []
DEBUG    -  Config value 'extra_javascript' = []
DEBUG    -  Config value 'extra_templates' = []
DEBUG    -  Config value 'markdown_extensions' = ['toc', 'tables', 'fenced_code', 'pymdownx.highlight', 'pymdownx.superfences']
DEBUG    -  Config value 'mdx_configs' = {}
DEBUG    -  Config value 'strict' = False
DEBUG    -  Config value 'remote_branch' = 'gh-pages'
DEBUG    -  Config value 'remote_name' = 'origin'
DEBUG    -  Config value 'extra' = {'social': [{'icon': 'fontawesome/brands/github', 'link': 'https://github.com/JakubAndrysek'}, {'icon': 'fontawesome/brands/twitter', 'link':
            'https://twitter.com/KubaAndrysek'}, {'icon': 'fontawesome/brands/linkedin', 'link': 'https://www.linkedin.com/in/jakub-andrysek/'}], 'analytics': {'provider': 'google',
            'property': 'G-6VB0GPP3MT', 'feedback': {'title': 'Was this page helpful?', 'ratings': [{'icon': 'material/emoticon-happy-outline', 'name': 'This page was helpful',
            'data': 1, 'note': 'Thanks for your feedback!'}, {'icon': 'material/emoticon-sad-outline', 'name': 'This page could be improved', 'data': 0, 'note': 'Thanks for your
            feedback!'}]}}}
DEBUG    -  Config value 'plugins' = {'material/search': <material.plugins.search.plugin.SearchPlugin object at 0x7fe71c3b3a50>, 'glightbox': <mkdocs_glightbox.plugin.LightboxPlugin
            object at 0x7fe71c485750>, 'open-in-new-tab': <open_in_new_tab.plugin.OpenInNewTabPlugin object at 0x7fe71c487bd0>, 'mkdoxy': <mkdoxy.plugin.MkDoxy object at
            0x7fe71c490590>}
DEBUG    -  Config value 'hooks' = {}
DEBUG    -  Config value 'watch' = []
DEBUG    -  Running 1 `startup` events
DEBUG    -  Running 2 `config` events
DEBUG    -  Looking for translations for locale 'en'
DEBUG    -  No translations found here: '/tmp/MkDoxy-demo/venv/lib/python3.11/site-packages/mkdocs/templates/locales'
DEBUG    -  No translations found here: '/tmp/MkDoxy-demo/venv/lib/python3.11/site-packages/material/locales'
DEBUG    -  Looking for translations for locale 'en'
DEBUG    -  No translations found here: '/tmp/MkDoxy-demo/venv/lib/python3.11/site-packages/mkdocs/templates/locales'
DEBUG    -  No translations found here: '/tmp/MkDoxy-demo/venv/lib/python3.11/site-packages/material/locales'
DEBUG    -  Looking for translations for locale 'en'
DEBUG    -  No translations found here: '/tmp/MkDoxy-demo/venv/lib/python3.11/site-packages/mkdocs/templates/locales'
DEBUG    -  No translations found here: '/tmp/MkDoxy-demo/venv/lib/python3.11/site-packages/material/locales'
INFO     -  Cleaning site directory
INFO     -  Building documentation to directory: /tmp/MkDoxy-demo/site
DEBUG    -  Looking for translations for locale 'en'
DEBUG    -  No translations found here: '/tmp/MkDoxy-demo/venv/lib/python3.11/site-packages/mkdocs/templates/locales'
DEBUG    -  No translations found here: '/tmp/MkDoxy-demo/venv/lib/python3.11/site-packages/material/locales'
DEBUG    -  Running 1 `files` events
INFO     -  Start plugin MkDoxy
INFO     -  -> Start project 'esp'
INFO     -    -> generating Doxygen filese
INFO     -  Overwriting template 'annotated' with custom template.
INFO     -  -> Start project 'animal'
INFO     -  -> Start project 'stm'
Traceback (most recent call last):
  File "/tmp/MkDoxy-demo/venv/bin/mkdocs", line 8, in <module>
    sys.exit(cli())
             ^^^^^
  File "/tmp/MkDoxy-demo/venv/lib/python3.11/site-packages/click/core.py", line 1130, in __call__
    return self.main(*args, **kwargs)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/tmp/MkDoxy-demo/venv/lib/python3.11/site-packages/click/core.py", line 1055, in main
    rv = self.invoke(ctx)
         ^^^^^^^^^^^^^^^^
  File "/tmp/MkDoxy-demo/venv/lib/python3.11/site-packages/click/core.py", line 1657, in invoke
    return _process_result(sub_ctx.command.invoke(sub_ctx))
                           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/tmp/MkDoxy-demo/venv/lib/python3.11/site-packages/click/core.py", line 1404, in invoke
    return ctx.invoke(self.callback, **ctx.params)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/tmp/MkDoxy-demo/venv/lib/python3.11/site-packages/click/core.py", line 760, in invoke
    return __callback(*args, **kwargs)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/tmp/MkDoxy-demo/venv/lib/python3.11/site-packages/mkdocs/__main__.py", line 250, in build_command
    build.build(cfg, dirty=not clean)
  File "/tmp/MkDoxy-demo/venv/lib/python3.11/site-packages/mkdocs/commands/build.py", line 297, in build
    files = config.plugins.run_event('files', files, config=config)
            ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/tmp/MkDoxy-demo/venv/lib/python3.11/site-packages/mkdocs/plugins.py", line 520, in run_event
    result = method(item, **kwargs)
             ^^^^^^^^^^^^^^^^^^^^^^
  File "/tmp/MkDoxy-demo/venv/lib/python3.11/site-packages/mkdoxy/plugin.py", line 125, in on_files
    self.doxygen[project_name] = Doxygen(doxygenRun.getOutputFolder(), parser=parser, cache=cache)
                                 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/tmp/MkDoxy-demo/venv/lib/python3.11/site-packages/mkdoxy/doxygen.py", line 107, in __init__
    self._recursive_sort(self.files)
  File "/tmp/MkDoxy-demo/venv/lib/python3.11/site-packages/mkdoxy/doxygen.py", line 122, in _recursive_sort
    self._recursive_sort(child)
  File "/tmp/MkDoxy-demo/venv/lib/python3.11/site-packages/mkdoxy/doxygen.py", line 122, in _recursive_sort
    self._recursive_sort(child)
  File "/tmp/MkDoxy-demo/venv/lib/python3.11/site-packages/mkdoxy/doxygen.py", line 122, in _recursive_sort
    self._recursive_sort(child)
  [Previous line repeated 1 more time]
  File "/tmp/MkDoxy-demo/venv/lib/python3.11/site-packages/mkdoxy/doxygen.py", line 120, in _recursive_sort
    node.sort_children()
  File "/tmp/MkDoxy-demo/venv/lib/python3.11/site-packages/mkdoxy/node.py", line 83, in sort_children
    self._children.sort(key=lambda x: x._name, reverse=False)
TypeError: '<' not supported between instances of 'NoneType' and 'str'
gladhorn commented 12 months ago

I have the same issue on a C++ code base. The problem is that some types that doxygen extracts don't have a sensible name. Anonymous namespaces for example are currently a problem. Also something like this is a problem:

struct Foo {
    union {
        int a;
        char b;
    };
};
heppson commented 12 months ago

I can confirm this issue on a C codebase with lots of anonymous structs and unions.

gladhorn commented 12 months ago

Somewhat hackish fix: https://github.com/reMarkable/MkDoxy/commit/0d97d7a0b777674d50f4318f07b08a0ea4cf0f37 - fixes the problem (for me) but I want to understand it properly before submitting a PR. Also I'm not sure what Doxygen generally does for anything that is unnamed. At some point I just had a long list of anonymous namespaces, which doesn't help anyone really.