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
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
|
import fnmatch
import os
import logging
from functools import cmp_to_key
from urllib.parse import quote as urlquote
from mkdocs import utils
log = logging.getLogger(__name__)
log.addFilter(utils.warning_filter)
class Files:
""" A collection of File objects. """
def __init__(self, files):
self._files = files
self.src_paths = {file.src_path: file for file in files}
def __iter__(self):
return iter(self._files)
def __len__(self):
return len(self._files)
def __contains__(self, path):
return path in self.src_paths
def get_file_from_path(self, path):
""" Return a File instance with File.src_path equal to path. """
return self.src_paths.get(os.path.normpath(path))
def append(self, file):
""" Append file to Files collection. """
self._files.append(file)
self.src_paths[file.src_path] = file
def copy_static_files(self, dirty=False):
""" Copy static files from source to destination. """
for file in self:
if not file.is_documentation_page():
file.copy_file(dirty)
def documentation_pages(self):
""" Return iterable of all Markdown page file objects. """
return [file for file in self if file.is_documentation_page()]
def static_pages(self):
""" Return iterable of all static page file objects. """
return [file for file in self if file.is_static_page()]
def media_files(self):
""" Return iterable of all file objects which are not documentation or static pages. """
return [file for file in self if file.is_media_file()]
def javascript_files(self):
""" Return iterable of all javascript file objects. """
return [file for file in self if file.is_javascript()]
def css_files(self):
""" Return iterable of all CSS file objects. """
return [file for file in self if file.is_css()]
def add_files_from_theme(self, env, config):
""" Retrieve static files from Jinja environment and add to collection. """
def filter(name):
# '.*' filters dot files/dirs at root level whereas '*/.*' filters nested levels
patterns = ['.*', '*/.*', '*.py', '*.pyc', '*.html', '*readme*', 'mkdocs_theme.yml']
patterns.extend('*{}'.format(x) for x in utils.markdown_extensions)
patterns.extend(config['theme'].static_templates)
for pattern in patterns:
if fnmatch.fnmatch(name.lower(), pattern):
return False
return True
for path in env.list_templates(filter_func=filter):
# Theme files do not override docs_dir files
path = os.path.normpath(path)
if path not in self:
for dir in config['theme'].dirs:
# Find the first theme dir which contains path
if os.path.isfile(os.path.join(dir, path)):
self.append(File(path, dir, config['site_dir'], config['use_directory_urls']))
break
class File:
"""
A MkDocs File object.
Points to the source and destination locations of a file.
The `path` argument must be a path that exists relative to `src_dir`.
The `src_dir` and `dest_dir` must be absolute paths on the local file system.
The `use_directory_urls` argument controls how destination paths are generated. If `False`, a Markdown file is
mapped to an HTML file of the same name (the file extension is changed to `.html`). If True, a Markdown file is
mapped to an HTML index file (`index.html`) nested in a directory using the "name" of the file in `path`. The
`use_directory_urls` argument has no effect on non-Markdown files.
File objects have the following properties, which are Unicode strings:
File.src_path
The pure path of the source file relative to the source directory.
File.abs_src_path
The absolute concrete path of the source file.
File.dest_path
The pure path of the destination file relative to the destination directory.
File.abs_dest_path
The absolute concrete path of the destination file.
File.url
The url of the destination file relative to the destination directory as a string.
"""
def __init__(self, path, src_dir, dest_dir, use_directory_urls):
self.page = None
self.src_path = os.path.normpath(path)
self.abs_src_path = os.path.normpath(os.path.join(src_dir, self.src_path))
self.name = self._get_stem()
self.dest_path = self._get_dest_path(use_directory_urls)
self.abs_dest_path = os.path.normpath(os.path.join(dest_dir, self.dest_path))
self.url = self._get_url(use_directory_urls)
def __eq__(self, other):
def sub_dict(d):
return {key: value for key, value in d.items() if key in ['src_path', 'abs_src_path', 'url']}
return (isinstance(other, self.__class__) and sub_dict(self.__dict__) == sub_dict(other.__dict__))
def __ne__(self, other):
return not self.__eq__(other)
def _get_stem(self):
""" Return the name of the file without it's extension. """
filename = os.path.basename(self.src_path)
stem, ext = os.path.splitext(filename)
return 'index' if stem in ('index', 'README') else stem
def _get_dest_path(self, use_directory_urls):
""" Return destination path based on source path. """
if self.is_documentation_page():
parent, filename = os.path.split(self.src_path)
if not use_directory_urls or self.name == 'index':
# index.md or README.md => index.html
# foo.md => foo.html
return os.path.join(parent, self.name + '.html')
else:
# foo.md => foo/index.html
return os.path.join(parent, self.name, 'index.html')
return self.src_path
def _get_url(self, use_directory_urls):
""" Return url based in destination path. """
url = self.dest_path.replace(os.path.sep, '/')
dirname, filename = os.path.split(url)
if use_directory_urls and filename == 'index.html':
if dirname == '':
url = '.'
else:
url = dirname + '/'
return urlquote(url)
def url_relative_to(self, other):
""" Return url for file relative to other file. """
return utils.get_relative_url(self.url, other.url if isinstance(other, File) else other)
def copy_file(self, dirty=False):
""" Copy source file to destination, ensuring parent directories exist. """
if dirty and not self.is_modified():
log.debug("Skip copying unmodified file: '{}'".format(self.src_path))
else:
log.debug("Copying media file: '{}'".format(self.src_path))
utils.copy_file(self.abs_src_path, self.abs_dest_path)
def is_modified(self):
if os.path.isfile(self.abs_dest_path):
return os.path.getmtime(self.abs_dest_path) < os.path.getmtime(self.abs_src_path)
return True
def is_documentation_page(self):
""" Return True if file is a Markdown page. """
return os.path.splitext(self.src_path)[1] in utils.markdown_extensions
def is_static_page(self):
""" Return True if file is a static page (html, xml, json). """
return os.path.splitext(self.src_path)[1] in (
'.html',
'.htm',
'.xml',
'.json',
)
def is_media_file(self):
""" Return True if file is not a documentation or static page. """
return not (self.is_documentation_page() or self.is_static_page())
def is_javascript(self):
""" Return True if file is a JavaScript file. """
return os.path.splitext(self.src_path)[1] in (
'.js',
'.javascript',
)
def is_css(self):
""" Return True if file is a CSS file. """
return os.path.splitext(self.src_path)[1] in (
'.css',
)
def get_files(config):
""" Walk the `docs_dir` and return a Files collection. """
files = []
exclude = ['.*', '/templates']
for source_dir, dirnames, filenames in os.walk(config['docs_dir'], followlinks=True):
relative_dir = os.path.relpath(source_dir, config['docs_dir'])
for dirname in list(dirnames):
path = os.path.normpath(os.path.join(relative_dir, dirname))
# Skip any excluded directories
if _filter_paths(basename=dirname, path=path, is_dir=True, exclude=exclude):
dirnames.remove(dirname)
dirnames.sort()
for filename in _sort_files(filenames):
path = os.path.normpath(os.path.join(relative_dir, filename))
# Skip any excluded files
if _filter_paths(basename=filename, path=path, is_dir=False, exclude=exclude):
continue
# Skip README.md if an index file also exists in dir
if filename.lower() == 'readme.md' and 'index.md' in filenames:
log.warning("Both index.md and readme.md found. Skipping readme.md from {}".format(source_dir))
continue
files.append(File(path, config['docs_dir'], config['site_dir'], config['use_directory_urls']))
return Files(files)
def _sort_files(filenames):
""" Always sort `index` or `README` as first filename in list. """
def compare(x, y):
if x == y:
return 0
if os.path.splitext(y)[0] in ['index', 'README']:
return 1
if os.path.splitext(x)[0] in ['index', 'README'] or x < y:
return -1
return 1
return sorted(filenames, key=cmp_to_key(compare))
def _filter_paths(basename, path, is_dir, exclude):
""" .gitignore style file filtering. """
for item in exclude:
# Items ending in '/' apply only to directories.
if item.endswith('/') and not is_dir:
continue
# Items starting with '/' apply to the whole path.
# In any other cases just the basename is used.
match = path if item.startswith('/') else basename
if fnmatch.fnmatch(match, item.strip('/')):
return True
return False
|
