BeautifulSoup4>=4.13.3 crashing Ultralytics Docs build

[glenn-jocher]

Latest versions of BeautifulSoup4 is not compatible with Ultralytics Docs builds.

Affects BeautifulSoup4==4.13.4 also

python docs/build_docs.py

ERROR   -  Error building page 'index.md': list index out of range
Traceback (most recent call last):
  File "/Users/glennjocher/PycharmProjects/.venv/bin/mkdocs", line 8, in <module>
    sys.exit(cli())
             ^^^^^
  File "/Users/glennjocher/PycharmProjects/.venv/lib/python3.12/site-packages/click/core.py", line 1161, in __call__
    return self.main(*args, **kwargs)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/Users/glennjocher/PycharmProjects/.venv/lib/python3.12/site-packages/click/core.py", line 1082, in main
    rv = self.invoke(ctx)
         ^^^^^^^^^^^^^^^^
  File "/Users/glennjocher/PycharmProjects/.venv/lib/python3.12/site-packages/click/core.py", line 1697, in invoke
    return _process_result(sub_ctx.command.invoke(sub_ctx))
                           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/Users/glennjocher/PycharmProjects/.venv/lib/python3.12/site-packages/click/core.py", line 1443, in invoke
    return ctx.invoke(self.callback, **ctx.params)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/Users/glennjocher/PycharmProjects/.venv/lib/python3.12/site-packages/click/core.py", line 788, in invoke
    return __callback(*args, **kwargs)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/Users/glennjocher/PycharmProjects/.venv/lib/python3.12/site-packages/mkdocs/__main__.py", line 288, in build_command
    build.build(cfg, dirty=not clean)
  File "/Users/glennjocher/PycharmProjects/.venv/lib/python3.12/site-packages/mkdocs/commands/build.py", line 337, in build
    _build_page(
  File "/Users/glennjocher/PycharmProjects/.venv/lib/python3.12/site-packages/mkdocs/commands/build.py", line 226, in _build_page
    output = config.plugins.on_post_page(output, page=page, config=config)
             ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/Users/glennjocher/PycharmProjects/.venv/lib/python3.12/site-packages/mkdocs/plugins.py", line 646, in on_post_page
    return self.run_event('post_page', output, page=page, config=config)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/Users/glennjocher/PycharmProjects/.venv/lib/python3.12/site-packages/mkdocs/plugins.py", line 566, in run_event
    result = method(item, **kwargs)
             ^^^^^^^^^^^^^^^^^^^^^^
  File "/Users/glennjocher/PycharmProjects/mkdocs/plugin/main.py", line 378, in on_post_page
    self.insert_content(soup, div)
  File "/Users/glennjocher/PycharmProjects/mkdocs/plugin/main.py", line 179, in insert_content
    md_typeset.append(content_to_insert)
  File "/Users/glennjocher/PycharmProjects/.venv/lib/python3.12/site-packages/bs4/element.py", line 2062, in append
    return self.insert(len(self.contents), tag)[0]
           ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~^^^
IndexError: list index out of range
Traceback (most recent call last):
  File "/Users/glennjocher/PycharmProjects/ultralytics/docs/build_docs.py", line 370, in <module>
    main()
  File "/Users/glennjocher/PycharmProjects/ultralytics/docs/build_docs.py", line 347, in main
    subprocess.run(f"mkdocs build -f {DOCS.parent}/mkdocs.yml --strict", check=True, shell=True)
  File "/Library/Frameworks/Python.framework/Versions/3.12/lib/python3.12/subprocess.py", line 571, in run
    raise CalledProcessError(retcode, process.args,
subprocess.CalledProcessError: Command 'mkdocs build -f /Users/glennjocher/PycharmProjects/ultralytics/mkdocs.yml --strict' returned non-zero exit status 1.

[UltralyticsAssistant]

👋 Hello @glenn-jocher, thank you for submitting a ultralytics/mkdocs 🚀 Issue. To help us address your concern efficiently, please ensure you've provided the following information:

1. For bug reports:

   • A clear and concise description of the bug
   • A minimum reproducible example MRE that demonstrates the issue 🐛
   • Your environment details (OS, Python version, package versions)
   • Expected behavior vs. actual behavior
   • Any error messages or logs related to the issue

2. For feature requests:

   • A clear and concise description of the proposed feature
   • The problem this feature would solve
   • Any alternative solutions you've considered

3. For questions:

   • Provide as much context as possible about your question
   • Include any research you've already done on the topic
   • Specify which parts of the documentation, if any, you've already consulted

In your case, since you're pointing out a compatibility issue with BeautifulSoup4, could you please provide:

• The exact versions of BeautifulSoup4 and any other related dependencies (e.g., mkdocs packages) you're using
• The steps to reproduce this crash with the latest BeautifulSoup4 version
• Any relevant error logs or stack traces during the build process

Please also make sure you've searched through existing issues to avoid duplicates. If you need to update your issue with more details, feel free to comment here.

This is an automated response to guide you in structuring your report correctly 😊. An Ultralytics engineer will be here to assist you soon. Thank you for helping us improve our project! 🚀

[UltralyticsAssistant]

A potential fix has been merged in the PR MetaPlugin fix for beautifulsoup4>=4.13.5: #156.

Key changes that may resolve this issue:

• Version bump to 0.1.29.
• Content insertion fix: switched a second if to elif to prevent duplicate or misplaced content when a __comments header is present.
• Dependency update to beautifulsoup4>=4.13.5 for improved compatibility.

Credit to @onuralpszr for the PR with contributions from @glenn-jocher.

How to test the fix:

• Install from source (main branch):
  pip install git+https://github.com/ultralytics/mkdocs.git@main
• Ensure the environment uses the updated dependency:
  pip install -U beautifulsoup4>=4.13.5
• Alternatively, wait for the next PyPI release and update to MetaPlugin version 0.1.29 or later once available.

Feedback on whether this resolves the issue would be appreciated. Thanks for reporting this, and please share any further details if the problem persists. 🙏