fixes for single-file doc-builder

[fchapoton]

This is restoring the ability to build the doc for any user-provided single file.

sage --docbuild  file=monkey_banana.py html

This has been broken since long. Now redone and using pathlib.Path

📝 Checklist

• The title is concise and informative.
• The description explains in detail what this PR is about.

[fchapoton]

@jhpalmieri : would you be interested in that ?

[fchapoton]

@jhpalmieri : would you be interested in that ?

[jhpalmieri]

Maybe this fixes #30475?

[fchapoton]

no, this still does not work for single files inside sage own code. Same for a file that I picked at random inside lmfdb

But it works for my own personal files, and it's my use case.

[github-actions]

Documentation preview for this PR (built with commit ec3b61e; changes) is ready! 🎉
This preview will update shortly after each push to this PR.

[jhpalmieri]

This only works for me if I do sage --docbuild file=foo.py html, but not sage --docbuild file=/path/to/foo.py html — it requires foo.py to be in the current working directory, or perhaps in a directory from which Python can import it. Is that the intended behavior? If I specify a path, I see

[html     ] building [html]: targets for 1 source files that are out of date
[html     ] updating environment: [new config] 1 added, 0 changed, 0 removed
[html     ] WARNING: autodoc: failed to import module 'foo'; the following exception was raised:
[html     ] ['Traceback (most recent call last):\n', '  File "/Users/palmieri/Sage/TESTING/clean/sage-10.7.beta9/local/var/lib/sage/venv-python3.13/lib/python3.13/site-packages/sphinx/ext/autodoc/importer.py", line 269, in import_object\n    module = import_module(modname, try_reload=True)\n', '  File "/Users/palmieri/Sage/TESTING/clean/sage-10.7.beta9/local/var/lib/sage/venv-python3.13/lib/python3.13/site-packages/sphinx/ext/autodoc/importer.py", line 172, in import_module\n    raise ModuleNotFoundError(msg, name=modname)  # NoQA: TRY301\n    ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^\n', "ModuleNotFoundError: No module named 'foo'\n"] [autodoc.import_object]
[html     ] The HTML pages are in ../../../../.sage/docbuild/foo/output/html.
Error building the documentation.
Traceback (most recent call last):
  File "<frozen runpy>", line 198, in _run_module_as_main
  File "<frozen runpy>", line 88, in _run_code
  File "/Users/palmieri/Sage/TESTING/clean/sage-10.7.beta9/src/sage_docbuild/__main__.py", line 553, in <module>
    sys.exit(main())
             ~~~~^^
  File "/Users/palmieri/Sage/TESTING/clean/sage-10.7.beta9/src/sage_docbuild/__main__.py", line 549, in main
    build()
    ~~~~~^^
  File "/Users/palmieri/Sage/TESTING/clean/sage-10.7.beta9/src/sage_docbuild/builders.py", line 136, in f
    runsphinx()
    ~~~~~~~~~^^
  File "/Users/palmieri/Sage/TESTING/clean/sage-10.7.beta9/src/sage_docbuild/sphinxbuild.py", line 324, in runsphinx
    sys.stderr.raise_errors()
    ~~~~~~~~~~~~~~~~~~~~~~~^^
  File "/Users/palmieri/Sage/TESTING/clean/sage-10.7.beta9/src/sage_docbuild/sphinxbuild.py", line 255, in raise_errors
    raise OSError(self._error)
OSError: WARNING: autodoc: failed to import module 'foo'; the following exception was raised:

and the documentation is not built correctly.

[fchapoton]

I am dropping the case, sorry.