search

sphinx-doc / sphinx

The Sphinx documentation generator
https://www.sphinx-doc.org/
Other
6.61k stars 2.13k forks source link

Add `copy_asset{_file}` to `doc/extdev/utils` #13077

Open jdillard opened 3 weeks ago

jdillard commented 3 weeks ago

Add copy_asset() and copy_asset_file() to the Sphinx API > Utilities page.

Preview:

Feature or Bugfix

Purpose

The page documents utility classes and functions to develop extensions with and I feel like copy_asset() and copy_asset_file() are common/valuable functions for extension development and should be highlighted in the docs.

The functions were added in version 1.5 via this PR: https://github.com/sphinx-doc/sphinx/pull/2744

jdillard commented 2 weeks ago

Thoughts on sphinx.util.osutil.copyfile()? copy_asset{_file} are really only useful if you want to render Jinja templates

Ah, I thought the rendering was acting as an optional addition, but you make a good point.

My use case is that I was playing around with a new extension and (under the current implementation) needed to copy a directory of files to the _static folder.

So in that instance, is it recommended to implement that recursively with sphinx.util.osutil.copyfile()? Or, should a sphinx.util.osutil.copydir() exist?

Or, would would best practice be to not use Sphinx for that functionality?

AA-Turner commented 1 week ago

To copy a directory, I would reach for shutil.copytree() in the first instance.

Although, this raises a different feature request. Themes can copy static files via copy_theme_static_files, but there's no option for extensions. Thoughts?

A