1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
|
"""Sphinx extension to collect additional files in the build directory.
This is used to copy files (indicated by glob patterns) from the source
directory into the destination build directory. Each destination file will be
in the same relative place in the tree.
This is useful when you have non-ReST/image files that you want part of your
built set of files, perhaps containing metadata or packaging that you want to
ship along with the documentation.
Setup
=====
To use this, you just need to add the extension in :file:`conf.py`::
extensions = [
...
'beanbag_docutils.sphinx.ext.collect_files',
...
]
And then configure ``collect_file_patterns`` to be a list of
filenames/glob patterns.
Configuration
=============
``collect_file_patterns``
List of filenames or glob patterns to include from the source directory
into the build directory.
"""
import os
import shutil
from fnmatch import fnmatch
def collect_files(app, env):
"""Collect configured files and put them into the build directory.
Args:
app (sphinx.application.Sphinx):
The Sphinx application to register roles and configuration on.
env (sphinx.environment.BuildEnvironment, unused):
The build environment for the generated docs.
"""
collect_patterns = app.config['collect_file_patterns']
src_dir = app.builder.srcdir
out_dir = app.builder.outdir
for root, dirs, files in os.walk(src_dir):
# Make sure we don't recurse into the build directory.
if root == src_dir:
try:
dirs.remove('_build')
except ValueError:
pass
for filename in files:
for pattern in collect_patterns:
if fnmatch(filename, pattern):
shutil.copy(os.path.join(root, filename),
os.path.join(out_dir,
os.path.relpath(root, src_dir),
filename))
break
def setup(app):
"""Set up the Sphinx extension.
This listens for the events needed to collect files.
Args:
app (sphinx.application.Sphinx):
The Sphinx application to listen to events on.
Returns:
dict:
Information about the extension.
"""
app.add_config_value('collect_file_patterns', {}, True)
app.connect('env-updated', collect_files)
return {
'version': '1.0',
'parallel_read_safe': True,
}
|
