mkdocs-redirects 1.2.1__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (8) hide show
  1. mkdocs_redirects/__init__.py +0 -0
  2. mkdocs_redirects/plugin.py +132 -0
  3. mkdocs_redirects-1.2.1.dist-info/LICENSE +21 -0
  4. mkdocs_redirects-1.2.1.dist-info/METADATA +131 -0
  5. mkdocs_redirects-1.2.1.dist-info/RECORD +8 -0
  6. mkdocs_redirects-1.2.1.dist-info/WHEEL +5 -0
  7. mkdocs_redirects-1.2.1.dist-info/entry_points.txt +2 -0
  8. mkdocs_redirects-1.2.1.dist-info/top_level.txt +1 -0
mkdocs_redirects/__init__.py ADDED
File without changes
mkdocs_redirects/plugin.py ADDED
@@ -0,0 +1,132 @@
1
+ """
2
+ Copyright 2019-2022 DataRobot, Inc. and its affiliates.
3
+ All rights reserved.
4
+ """
5
+ import logging
6
+ import os
7
+ import posixpath
8
+
9
+ from mkdocs import utils
10
+ from mkdocs.config import config_options
11
+ from mkdocs.plugins import BasePlugin
12
+ from mkdocs.structure.files import File
13
+
14
+ log = logging.getLogger('mkdocs.plugin.redirects')
15
+
16
+
17
+ HTML_TEMPLATE = """
18
+ <!doctype html>
19
+ <html lang="en">
20
+ <head>
21
+ <meta charset="utf-8">
22
+ <title>Redirecting...</title>
23
+ <link rel="canonical" href="{url}">
24
+ <meta name="robots" content="noindex">
25
+ <script>var anchor=window.location.hash.substr(1);location.href="{url}"+(anchor?"#"+anchor:"")</script>
26
+ <meta http-equiv="refresh" content="0; url={url}">
27
+ </head>
28
+ <body>
29
+ Redirecting...
30
+ </body>
31
+ </html>
32
+ """
33
+
34
+
35
+ def write_html(site_dir, old_path, new_path):
36
+ """Write an HTML file in the site_dir with a meta redirect to the new page"""
37
+ # Determine all relevant paths
38
+ old_path_abs = os.path.join(site_dir, old_path)
39
+ old_dir = os.path.dirname(old_path)
40
+ old_dir_abs = os.path.dirname(old_path_abs)
41
+
42
+ # Create parent directories if they don't exist
43
+ if not os.path.exists(old_dir_abs):
44
+ log.debug("Creating directory '%s'", old_dir)
45
+ os.makedirs(old_dir_abs)
46
+
47
+ # Write the HTML redirect file in place of the old file
48
+ log.debug("Creating redirect: '%s' -> '%s'", old_path, new_path)
49
+ content = HTML_TEMPLATE.format(url=new_path)
50
+ with open(old_path_abs, 'w', encoding='utf-8') as f:
51
+ f.write(content)
52
+
53
+
54
+ def get_relative_html_path(old_page, new_page, use_directory_urls):
55
+ """Return the relative path from the old html path to the new html path"""
56
+ old_path = get_html_path(old_page, use_directory_urls)
57
+ new_path, new_hash_fragment = _split_hash_fragment(new_page)
58
+
59
+ relative_path = posixpath.relpath(new_path, start=posixpath.dirname(old_path))
60
+ if use_directory_urls:
61
+ relative_path = relative_path + '/'
62
+
63
+ return relative_path + new_hash_fragment
64
+
65
+
66
+ def get_html_path(path, use_directory_urls):
67
+ """Return the HTML file path for a given markdown file"""
68
+ f = File(path, '', '', use_directory_urls)
69
+ return f.dest_path.replace(os.sep, '/')
70
+
71
+
72
+ class RedirectPlugin(BasePlugin):
73
+ # Any options that this plugin supplies should go here.
74
+ config_scheme = (
75
+ ('redirect_maps', config_options.Type(dict, default={})), # note the trailing comma
76
+ )
77
+
78
+ # Build a list of redirects on file generation
79
+ def on_files(self, files, config, **kwargs):
80
+ self.redirects = self.config.get('redirect_maps', {})
81
+
82
+ # Validate user-provided redirect "old files"
83
+ for page_old in self.redirects.keys():
84
+ if not utils.is_markdown_file(page_old):
85
+ log.warning("redirects plugin: '%s' is not a valid markdown file!", page_old)
86
+
87
+ # Build a dict of known document pages to validate against later
88
+ self.doc_pages = {}
89
+ for page in files.documentation_pages(): # object type: mkdocs.structure.files.File
90
+ self.doc_pages[page.src_path.replace(os.sep, '/')] = page
91
+
92
+ # Create HTML files for redirects after site dir has been built
93
+ def on_post_build(self, config, **kwargs):
94
+ # Determine if 'use_directory_urls' is set
95
+ use_directory_urls = config.get('use_directory_urls')
96
+
97
+ # Walk through the redirect map and write their HTML files
98
+ for page_old, page_new in self.redirects.items():
99
+ # Need to remove hash fragment from new page to verify existence
100
+ page_new_without_hash, hash = _split_hash_fragment(str(page_new))
101
+
102
+ # External redirect targets are easy, just use it as the target path
103
+ if page_new.lower().startswith(('http://', 'https://')):
104
+ dest_path = page_new
105
+
106
+ elif page_new_without_hash in self.doc_pages:
107
+ file = self.doc_pages[page_new_without_hash]
108
+ dest_path = get_relative_html_path(page_old, file.url + hash, use_directory_urls)
109
+
110
+ # If the redirect target isn't external or a valid internal page, throw an error
111
+ # Note: we use 'warn' here specifically; mkdocs treats warnings specially when in strict mode
112
+ else:
113
+ log.warning("Redirect target '%s' does not exist!", page_new)
114
+ continue
115
+
116
+ # DO IT!
117
+ write_html(
118
+ config['site_dir'],
119
+ get_html_path(page_old, use_directory_urls),
120
+ dest_path,
121
+ )
122
+
123
+
124
+ def _split_hash_fragment(path):
125
+ """
126
+ Returns (path, hash-fragment)
127
+
128
+ "path/to/file#hash" => ("/path/to/file", "#hash")
129
+ "path/to/file" => ("/path/to/file", "")
130
+ """
131
+ path, hash, after = path.partition('#')
132
+ return path, hash + after
mkdocs_redirects-1.2.1.dist-info/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2019-2022 DataRobot
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
mkdocs_redirects-1.2.1.dist-info/METADATA ADDED
@@ -0,0 +1,131 @@
1
+ Metadata-Version: 2.1
2
+ Name: mkdocs-redirects
3
+ Version: 1.2.1
4
+ Summary: A MkDocs plugin for dynamic page redirects to prevent broken links.
5
+ Home-page: https://github.com/datarobot/mkdocs-redirects
6
+ Author: Dustin Burke
7
+ Author-email: dustin@datarobot.com
8
+ License: MIT
9
+ Keywords: mkdocs redirect
10
+ Classifier: Development Status :: 4 - Beta
11
+ Classifier: Intended Audience :: Developers
12
+ Classifier: Intended Audience :: Information Technology
13
+ Classifier: License :: OSI Approved :: MIT License
14
+ Classifier: Programming Language :: Python
15
+ Classifier: Programming Language :: Python :: 3
16
+ Classifier: Programming Language :: Python :: 3.6
17
+ Classifier: Programming Language :: Python :: 3.7
18
+ Classifier: Programming Language :: Python :: 3.8
19
+ Classifier: Programming Language :: Python :: 3.9
20
+ Classifier: Programming Language :: Python :: 3.10
21
+ Requires-Python: >=3.6
22
+ Description-Content-Type: text/markdown
23
+ License-File: LICENSE
24
+ Requires-Dist: mkdocs >=1.1.1
25
+ Provides-Extra: dev
26
+ Requires-Dist: pytest ; extra == 'dev'
27
+ Requires-Dist: black ; extra == 'dev'
28
+ Requires-Dist: isort ; extra == 'dev'
29
+ Requires-Dist: autoflake ; extra == 'dev'
30
+ Requires-Dist: twine >=1.13.0 ; extra == 'dev'
31
+ Provides-Extra: release
32
+ Requires-Dist: twine >=1.13.0 ; extra == 'release'
33
+ Provides-Extra: test
34
+ Requires-Dist: pytest ; extra == 'test'
35
+ Requires-Dist: black ; extra == 'test'
36
+ Requires-Dist: isort ; extra == 'test'
37
+ Requires-Dist: autoflake ; extra == 'test'
38
+
39
+ # mkdocs-redirects
40
+
41
+ Plugin for [`mkdocs`](https://www.mkdocs.org/) to create page redirects (e.g. for moved/renamed pages).
42
+
43
+ Initially developed by [DataRobot](https://www.datarobot.com/).
44
+
45
+ ## Installing
46
+
47
+ > **Note:** This package requires MkDocs version 1.0.4 or higher.
48
+
49
+ Install with pip:
50
+
51
+ ```bash
52
+ pip install mkdocs-redirects
53
+ ```
54
+
55
+ ## Using
56
+
57
+ To use this plugin, specify your desired redirects in the plugin's `redirect_maps` setting in your `mkdocs.yml`:
58
+
59
+ ```yaml
60
+ plugins:
61
+ - redirects:
62
+ redirect_maps:
63
+ 'old.md': 'new.md'
64
+ 'old/file.md': 'new/file.md'
65
+ 'some_file.md': 'http://external.url.com/foobar'
66
+ ```
67
+
68
+ _Note: don't forget that specifying the `plugins` setting will override the defaults if you didn't already have it set! See [this page](https://www.mkdocs.org/user-guide/configuration/#plugins) for more information._
69
+
70
+ The redirects map should take the form of a key/value pair:
71
+
72
+ - The key of each redirect is the original _markdown doc_ (relative to the `docs_dir` path).
73
+ - This plugin will handle the filename resolution during the `mkdocs build` process.
74
+ This should be set to what the original markdown doc's filename was (or what it _would be_ if it existed), not the final HTML file rendered by MkDocs
75
+ - The value is the _redirect target_. This can take the following forms:
76
+ - Path of the _markdown doc_ you wish to be redirected to (relative to `docs_dir`)
77
+ - This plugin will handle the filename resolution during the `mkdocs build` process.
78
+ This should be set to what the markdown doc's filename is, not the final HTML file rendered by MkDocs
79
+ - External URL (e.g. `http://example.com`)
80
+
81
+ During the `mkdocs build` process, this plugin will create `.html` files in `site_dir` for each of the "old" file that redirects to the "new" path.
82
+ It will produce a warning if any problems are encountered or of the redirect target doesn't actually exist (useful if you have `strict: true` set).
83
+
84
+ ### `use_directory_urls`
85
+
86
+ If you have `use_directory_urls: true` set (which is the default), this plugin will modify the redirect targets to the _directory_ URL, not the _actual_ `index.html` filename.
87
+ However, it will create the `index.html` file for each target in the correct place so URL resolution works.
88
+
89
+ For example, a redirect map of `'old/dir/README.md': 'new/dir/README.md'` will result in an HTML file created at `$site_dir/old/dir/index.html` which redirects to `../../new/dir/`.
90
+
91
+ Additionally, a redirect map of `'old/dir/doc_name.md': 'new/dir/doc_name.md'` will result in `$site_dir/old/dir/doc_name/index.html` redirecting to `../../new/dir/doc_name/`.
92
+
93
+ This mimics the behavior of how MkDocs builds the site dir without this plugin.
94
+
95
+ ## Developing
96
+
97
+ ### Setup a virtualenv
98
+
99
+ Create a virtualenv using a method of your choice.
100
+
101
+ ```bash
102
+ brew install pyenv pyenv-virtualenv
103
+ pyenv install 2.7.18
104
+ pyenv virtualenv 2.7.18 mkdocs-redirects
105
+ pyenv activate mkdocs-redirects
106
+ ```
107
+
108
+ ### Build
109
+
110
+ ```bash
111
+ make build
112
+ ```
113
+
114
+ ### Test
115
+
116
+ ```bash
117
+ make test
118
+ ```
119
+
120
+ ## Releasing
121
+
122
+ ```bash
123
+ make release
124
+ ```
125
+
126
+ It will prompt you for your PyPI user and password.
127
+
128
+ See:
129
+
130
+ - <https://packaging.python.org/tutorials/packaging-projects/>
131
+ - <https://packaging.python.org/guides/migrating-to-pypi-org/>
mkdocs_redirects-1.2.1.dist-info/RECORD ADDED
@@ -0,0 +1,8 @@
1
+ mkdocs_redirects/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
2
+ mkdocs_redirects/plugin.py,sha256=Gj9gKAMh0kw5JK8BPfhWauC5DHlAQDeVnezBbqaBauM,4740
3
+ mkdocs_redirects-1.2.1.dist-info/LICENSE,sha256=4UFFAssftx-AlrOu9r54pz0ADUaHcBeZ1uJ8baEX1U4,1071
4
+ mkdocs_redirects-1.2.1.dist-info/METADATA,sha256=KcQksJ3zsz3e4sCjZZ2rKlHkFdQ5OC4RAS8A12zET2o,4663
5
+ mkdocs_redirects-1.2.1.dist-info/WHEEL,sha256=GJ7t_kWBFywbagK5eo9IoUwLW6oyOeTKmQ-9iHFVNxQ,92
6
+ mkdocs_redirects-1.2.1.dist-info/entry_points.txt,sha256=zTxw_2kwFAUnSjM-HTdshd3L07qZ5vUPAa82ugjhPFE,68
7
+ mkdocs_redirects-1.2.1.dist-info/top_level.txt,sha256=NRpkLn6UHMkXkhQ1Al1l_AuliEby4nMwJg4bZzmasBo,17
8
+ mkdocs_redirects-1.2.1.dist-info/RECORD,,
mkdocs_redirects-1.2.1.dist-info/WHEEL ADDED
@@ -0,0 +1,5 @@
1
+ Wheel-Version: 1.0
2
+ Generator: bdist_wheel (0.43.0)
3
+ Root-Is-Purelib: true
4
+ Tag: py3-none-any
5
+
mkdocs_redirects-1.2.1.dist-info/entry_points.txt ADDED
@@ -0,0 +1,2 @@
1
+ [mkdocs.plugins]
2
+ redirects = mkdocs_redirects.plugin:RedirectPlugin
mkdocs_redirects-1.2.1.dist-info/top_level.txt ADDED
@@ -0,0 +1 @@
1
+ mkdocs_redirects