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
|
import logging
from urllib.parse import urlparse
from mkdocs.structure.pages import Page
from mkdocs.utils import nest_paths, warning_filter
log = logging.getLogger(__name__)
log.addFilter(warning_filter)
class Navigation:
def __init__(self, items, pages):
self.items = items # Nested List with full navigation of Sections, Pages, and Links.
self.pages = pages # Flat List of subset of Pages in nav, in order.
self.homepage = None
for page in pages:
if page.is_homepage:
self.homepage = page
break
def __repr__(self):
return '\n'.join([item._indent_print() for item in self])
def __iter__(self):
return iter(self.items)
def __len__(self):
return len(self.items)
class Section:
def __init__(self, title, children):
self.title = title
self.children = children
self.parent = None
self.active = False
self.is_section = True
self.is_page = False
self.is_link = False
def __repr__(self):
return "Section(title='{}')".format(self.title)
def _get_active(self):
""" Return active status of section. """
return self.__active
def _set_active(self, value):
""" Set active status of section and ancestors. """
self.__active = bool(value)
if self.parent is not None:
self.parent.active = bool(value)
active = property(_get_active, _set_active)
@property
def ancestors(self):
if self.parent is None:
return []
return [self.parent] + self.parent.ancestors
def _indent_print(self, depth=0):
ret = ['{}{}'.format(' ' * depth, repr(self))]
for item in self.children:
ret.append(item._indent_print(depth + 1))
return '\n'.join(ret)
class Link:
def __init__(self, title, url):
self.title = title
self.url = url
self.parent = None
# These should never change but are included for consistency with sections and pages.
self.children = None
self.active = False
self.is_section = False
self.is_page = False
self.is_link = True
def __repr__(self):
title = "'{}'".format(self.title) if (self.title is not None) else '[blank]'
return "Link(title={}, url='{}')".format(title, self.url)
@property
def ancestors(self):
if self.parent is None:
return []
return [self.parent] + self.parent.ancestors
def _indent_print(self, depth=0):
return '{}{}'.format(' ' * depth, repr(self))
def get_navigation(files, config):
""" Build site navigation from config and files."""
nav_config = config['nav'] or nest_paths(f.src_path for f in files.documentation_pages())
items = _data_to_navigation(nav_config, files, config)
if not isinstance(items, list):
items = [items]
# Get only the pages from the navigation, ignoring any sections and links.
pages = _get_by_type(items, Page)
# Include next, previous and parent links.
_add_previous_and_next_links(pages)
_add_parent_links(items)
missing_from_config = [file for file in files.documentation_pages() if file.page is None]
if missing_from_config:
log.info(
'The following pages exist in the docs directory, but are not '
'included in the "nav" configuration:\n - {}'.format(
'\n - '.join([file.src_path for file in missing_from_config]))
)
# Any documentation files not found in the nav should still have an associated page, so we
# create them here. The Page object will automatically be assigned to `file.page` during
# its creation (and this is the only way in which these page objects are accessable).
for file in missing_from_config:
Page(None, file, config)
links = _get_by_type(items, Link)
for link in links:
scheme, netloc, path, params, query, fragment = urlparse(link.url)
if scheme or netloc:
log.debug(
"An external link to '{}' is included in "
"the 'nav' configuration.".format(link.url)
)
elif link.url.startswith('/'):
log.debug(
"An absolute path to '{}' is included in the 'nav' configuration, "
"which presumably points to an external resource.".format(link.url)
)
else:
msg = (
"A relative path to '{}' is included in the 'nav' configuration, "
"which is not found in the documentation files".format(link.url)
)
log.warning(msg)
return Navigation(items, pages)
def _data_to_navigation(data, files, config):
if isinstance(data, dict):
return [
_data_to_navigation((key, value), files, config)
if isinstance(value, str) else
Section(title=key, children=_data_to_navigation(value, files, config))
for key, value in data.items()
]
elif isinstance(data, list):
return [
_data_to_navigation(item, files, config)[0]
if isinstance(item, dict) and len(item) == 1 else
_data_to_navigation(item, files, config)
for item in data
]
title, path = data if isinstance(data, tuple) else (None, data)
file = files.get_file_from_path(path)
if file:
return Page(title, file, config)
return Link(title, path)
def _get_by_type(nav, T):
ret = []
for item in nav:
if isinstance(item, T):
ret.append(item)
elif item.children:
ret.extend(_get_by_type(item.children, T))
return ret
def _add_parent_links(nav):
for item in nav:
if item.is_section:
for child in item.children:
child.parent = item
_add_parent_links(item.children)
def _add_previous_and_next_links(pages):
bookended = [None] + pages + [None]
zipped = zip(bookended[:-2], bookended[1:-1], bookended[2:])
for page0, page1, page2 in zipped:
page1.previous_page, page1.next_page = page0, page2
|
