Issue: Build Failure on Read the Docs but Works Locally

[nmhjklnm]

Project Name: -xproxy

Read the Docs Username: nmhjklnm

Link to the failing build: Link to Build

Description: I am experiencing a build failure on Read the Docs, although the build works perfectly fine locally. The error seems to be related to mkdocstrings not being able to find certain classes in my project.

Error Log:

INFO    -  mkdocs_static_i18n: Building 'en' documentation to directory: /home/docs/checkouts/readthedocs.org/user_builds/xproxy/checkouts/latest/_readthedocs/html
INFO    -  Cleaning site directory
INFO    -  Building documentation to directory: /home/docs/checkouts/readthedocs.org/user_builds/xproxy/checkouts/latest/_readthedocs/html
ERROR   -  mkdocstrings: xproxy.manager.base.Proxy could not be found
ERROR   -  Error reading page 'en/ API Reference/index.md':
ERROR   -  Could not collect 'xproxy.manager.base.Proxy'
Aborted with a BuildError!

Steps to Reproduce:

1. Configure readthedocs.yml as follows:

   version: 2
   
   build:
     os: ubuntu-20.04
     tools:
       python: "3.10"
   
   python:
     install:
       - requirements: docs/requirements.txt
   
   mkdocs:
     configuration: mkdocs.yml

2. Configure mkdocs.yml as follows:

   
   site_name: xproxy docs
   site_url: https://xproxy.readthedocs.com
   repo_url: https://github.com/nmhjklnm/xproxy

theme: name: material icon: repo: fontawesome/brands/git-alt extra_css:

• docs/extra.css repo_name: xproxy features:
  • navigation.tabs

plugins:

• search: lang:

  • en
  • zh

• i18n: docs_structure: folder languages:

  • locale: en default: true name: English build: true
  • locale: zh name: 简体中文 build: true

• mkdocstrings: handlers: python: options: docstring_style: google show_source: true show_bases: true heading_level: 3 show_root_heading: true show_root_full_path: false allow_inspection: true parameter_headings: true

  3. Ensure `docs/requirements.txt` includes:
  ```txt
  mkdocs
  mkdocs-i18n
  mkdocs-static-i18n
  mkdocs-minify-plugin
  mkdocs-material
  mkdocstrings[python]

4. Ensure the following structure and content in the project:

   # xproxy/manager/base.py
   class Proxy:
       def __init__(self):
           pass
   
   class ProxyManager:
       def __init__(self):
           pass

   # xproxy/manager/__init__.py
   from .base import Proxy, ProxyManager

   # Base
   
   ::: xproxy.manager.Proxy
   
   ::: xproxy.manager.ProxyManager

What I Have Tried:

• Verified that the build works locally using mkdocs serve.
• Ensured all dependencies are listed in docs/requirements.txt.
• Cleared Read the Docs cache and retried the build.
• Verified that the module paths and imports are correct.

Additional Information:

• Python version: 3.10
• MkDocs version: 1.4.2
• Mkdocstrings version: 0.15.0
• Mkdocs-material version: 8.1.0

Expected Behavior: The documentation should build successfully on Read the Docs as it does locally.

[nmhjklnm]

@readthedocs-readthedocs

Hi team,

I wanted to follow up on this issue as I haven't received any response yet. This problem is blocking our documentation build on Read the Docs, and we would appreciate any guidance or assistance you can provide.

Please let me know if you need any additional information or if there's anything I can do to help resolve this issue.

Thank you!

[nmhjklnm]

Could you please provide an update on this issue? Thank you!

[ericholscher]

@nmhjklnm This is a free support channel, and we don't support project specific build issues. I'd ensure your project builds with the same config on a fresh virtualenv locally, as usually you have a configuration issue.

[pawamoy]

@nmhjklnm if you use the src-layout, make sure to add src to mkdocstrings' paths option. If not, maybe you need to also install the project itself in the Readthedocs build. Try passing -v to mkdocs build to get more logs.