File: pages.py

package info (click to toggle)
python-mkdocs 1.1.2%2Bdfsg-1
  • links: PTS, VCS
  • area: main
  • in suites: bullseye
  • size: 1,832 kB
  • sloc: python: 7,504; javascript: 2,299; perl: 142; sh: 66; makefile: 25; xml: 21
file content (244 lines) | stat: -rw-r--r-- 7,897 bytes parent folder | download
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
import os
import logging
from urllib.parse import urlparse, urlunparse, urljoin
from urllib.parse import unquote as urlunquote

import markdown
from markdown.extensions import Extension
from markdown.treeprocessors import Treeprocessor
from markdown.util import AMP_SUBSTITUTE

from mkdocs.structure.toc import get_toc
from mkdocs.utils import meta, get_build_date, get_markdown_title, warning_filter

log = logging.getLogger(__name__)
log.addFilter(warning_filter)


class Page:
    def __init__(self, title, file, config):
        file.page = self
        self.file = file
        self.title = title

        # Navigation attributes
        self.parent = None
        self.children = None
        self.previous_page = None
        self.next_page = None
        self.active = False

        self.is_section = False
        self.is_page = True
        self.is_link = False

        self.update_date = get_build_date()

        self._set_canonical_url(config.get('site_url', None))
        self._set_edit_url(config.get('repo_url', None), config.get('edit_uri', None))

        # Placeholders to be filled in later in the build process.
        self.markdown = None
        self.content = None
        self.toc = []
        self.meta = {}

    def __eq__(self, other):

        def sub_dict(d):
            return {key: value for key, value in d.items() if key in ['title', 'file']}

        return (isinstance(other, self.__class__) and sub_dict(self.__dict__) == sub_dict(other.__dict__))

    def __ne__(self, other):
        return not self.__eq__(other)

    def __repr__(self):
        title = "'{}'".format(self.title) if (self.title is not None) else '[blank]'
        return "Page(title={}, url='{}')".format(title, self.abs_url or self.file.url)

    def _indent_print(self, depth=0):
        return '{}{}'.format('    ' * depth, repr(self))

    def _get_active(self):
        """ Return active status of page. """
        return self.__active

    def _set_active(self, value):
        """ Set active status of page 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 is_index(self):
        return self.file.name == 'index'

    @property
    def is_top_level(self):
        return self.parent is None

    @property
    def is_homepage(self):
        return self.is_top_level and self.is_index and self.file.url == '.'

    @property
    def url(self):
        return '' if self.file.url == '.' else self.file.url

    @property
    def ancestors(self):
        if self.parent is None:
            return []
        return [self.parent] + self.parent.ancestors

    def _set_canonical_url(self, base):
        if base:
            if not base.endswith('/'):
                base += '/'
            self.canonical_url = urljoin(base, self.url)
            self.abs_url = urlparse(self.canonical_url).path
        else:
            self.canonical_url = None
            self.abs_url = None

    def _set_edit_url(self, repo_url, edit_uri):
        if repo_url and edit_uri:
            src_path = self.file.src_path.replace('\\', '/')
            self.edit_url = urljoin(repo_url, edit_uri + src_path)
        else:
            self.edit_url = None

    def read_source(self, config):
        source = config['plugins'].run_event(
            'page_read_source', page=self, config=config
        )
        if source is None:
            try:
                with open(self.file.abs_src_path, 'r', encoding='utf-8-sig', errors='strict') as f:
                    source = f.read()
            except OSError:
                log.error('File not found: {}'.format(self.file.src_path))
                raise
            except ValueError:
                log.error('Encoding error reading file: {}'.format(self.file.src_path))
                raise

        self.markdown, self.meta = meta.get_data(source)
        self._set_title()

    def _set_title(self):
        """
        Set the title for a Markdown document.

        Check these in order and use the first that returns a valid title:
        - value provided on init (passed in from config)
        - value of metadata 'title'
        - content of the first H1 in Markdown content
        - convert filename to title
        """
        if self.title is not None:
            return

        if 'title' in self.meta:
            self.title = self.meta['title']
            return

        title = get_markdown_title(self.markdown)

        if title is None:
            if self.is_homepage:
                title = 'Home'
            else:
                title = self.file.name.replace('-', ' ').replace('_', ' ')
                # Capitalize if the filename was all lowercase, otherwise leave it as-is.
                if title.lower() == title:
                    title = title.capitalize()

        self.title = title

    def render(self, config, files):
        """
        Convert the Markdown source file to HTML as per the config.
        """

        extensions = [
            _RelativePathExtension(self.file, files)
        ] + config['markdown_extensions']

        md = markdown.Markdown(
            extensions=extensions,
            extension_configs=config['mdx_configs'] or {}
        )
        self.content = md.convert(self.markdown)
        self.toc = get_toc(getattr(md, 'toc_tokens', []))


class _RelativePathTreeprocessor(Treeprocessor):
    def __init__(self, file, files):
        self.file = file
        self.files = files

    def run(self, root):
        """
        Update urls on anchors and images to make them relative

        Iterates through the full document tree looking for specific
        tags and then makes them relative based on the site navigation
        """
        for element in root.iter():
            if element.tag == 'a':
                key = 'href'
            elif element.tag == 'img':
                key = 'src'
            else:
                continue

            url = element.get(key)
            new_url = self.path_to_url(url)
            element.set(key, new_url)

        return root

    def path_to_url(self, url):
        scheme, netloc, path, params, query, fragment = urlparse(url)

        if (scheme or netloc or not path or url.startswith('/') or url.startswith('\\')
                or AMP_SUBSTITUTE in url or '.' not in os.path.split(path)[-1]):
            # Ignore URLs unless they are a relative link to a source file.
            # AMP_SUBSTITUTE is used internally by Markdown only for email.
            # No '.' in the last part of a path indicates path does not point to a file.
            return url

        # Determine the filepath of the target.
        target_path = os.path.join(os.path.dirname(self.file.src_path), urlunquote(path))
        target_path = os.path.normpath(target_path).lstrip(os.sep)

        # Validate that the target exists in files collection.
        if target_path not in self.files:
            log.warning(
                "Documentation file '{}' contains a link to '{}' which is not found "
                "in the documentation files.".format(self.file.src_path, target_path)
            )
            return url
        target_file = self.files.get_file_from_path(target_path)
        path = target_file.url_relative_to(self.file)
        components = (scheme, netloc, path, params, query, fragment)
        return urlunparse(components)


class _RelativePathExtension(Extension):
    """
    The Extension class is what we pass to markdown, it then
    registers the Treeprocessor.
    """

    def __init__(self, file, files):
        self.file = file
        self.files = files

    def extendMarkdown(self, md):
        relpath = _RelativePathTreeprocessor(self.file, self.files)
        md.treeprocessors.register(relpath, "relpath", 0)