Skip to content

Better error message when Sphinx extension fails at end of build due to renamed output path #728

@jgarbers

Description

@jgarbers

I've just started using pydoctor.sphinx_ext.build_apidocs in my documentation project, replacing Sphinx's autodoc. After adding the extension and pydoctor_args to my conf.py, sphinx-build fails with this error:

Handler <function on_build_finished at 0x1090307c0> for event 'build-finished' threw an exception (exception: [Errno 2] No such file or directory: '/Users/jgarbers3/lab/ev/docs/build/html/api' -> '/Users/jgarbers3/lab/ev/docs/build/html/api.sphinx_files')

My sphinx-build output path is set to "docs/build", and the extension configuration specifies "--html-output={outdir}/api/".

Reviewing the source for the extension, I think I have an idea of why this is failing. At the end of on_builder_inited, the extension renames the output path (here, "docs/build/html/api") to include a .pydoctor_temp suffix. Then, in on_build_finished, the code tries to rename the original output path ("docs/build/html/api") to include a .sphinx_files suffix. However, that path does not exist, since it was renamed to "docs/build/html/api.pydoctor_temp" at the end of the build init event handler, and the exception shown above triggers.

I've patched the extension to work around the error, and as a newcomer to pydoctor it seems likely that I've missed something. But I don't see any other references to what a .sphinx_files directory might be for, so I'm wondering if that rename step might have been left in inadvertently.

I'm using Python 3.11.3, Sphinx 7.0.1 and the pydoctor extension 23.4.1.

Thanks in advance for any guidance anyone can offer!

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions