Add copy_asset{_file} to doc/extdev/utils

[jdillard]

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

Preview:

• sphinx.util.fileutil.copy_asset
• sphinx.util.fileutil.copy_asset_file

Feature or Bugfix

• Feature

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: #2744

[picnixz]

Seems a good addition to me.

@AA-Turner Do you have future plans in making sphinx.util.* more private or not?

[AA-Turner]

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

[jdillard]

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]

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