Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
103 lines (87 sloc) 3.58 KB
import re
def setup(app):
app.connect('doctree-resolved', transform_github_links)
return {'version': '0.1'}
# Maps from files in docs/ to folders/files in repo
includes_mapping = {
r'^index$': r'',
r'^(providers|plugins)/index$': r'bootstrapvz/\1/',
r'^(providers|plugins)/(?!index)([^/]+)$': r'bootstrapvz/\1/\2/',
r'^manifests/index$': r'manifest/',
r'^manifests/official_([^_]+)_manifests$': r'manifest/official/\1/',
r'^testing/index$': r'tests/',
r'^testing/(?!index)([^/]+)_tests$': r'tests/\1/',
r'^remote_bootstrapping$': r'bootstrapvz/remote/',
r'^developers/index$': r'bootstrapvz/',
r'^developers/contributing$': r'CONTRIBUTING.rst',
r'^developers/documentation$': r'docs/',
r'^changelog$': r'CHANGELOG.rst',
# Maps from links in repo to files/folders in docs/
links_mapping = {
r'^$': r'',
r'^bootstrapvz/(providers|plugins)$': r'\1',
r'^bootstrapvz/(providers|plugins)/([^/]+)$': r'\1/\2.html',
r'^tests$': r'testing',
r'^manifests$': r'manifests',
r'^manifests/official/([^/]+)$': r'manifests/official_\1_manifests.html',
r'^tests/([^/]+)$': r'testing/\1_tests.html',
r'^bootstrapvz/remote$': r'remote_bootstrapping.html',
r'^bootstrapvz$': r'developers',
r'^CONTRIBUTING\.rst$': r'developers/contributing.html',
r'^docs$': r'developers/documentation.html',
r'^CHANGELOG\.rst$': r'changelog.html',
for key, val in includes_mapping.items():
del includes_mapping[key]
includes_mapping[re.compile(key)] = val
for key, val in links_mapping.items():
del links_mapping[key]
links_mapping[re.compile(key)] = val
def find_original(path):
for key, val in includes_mapping.items():
if re.match(key, path):
return re.sub(key, val, path)
return None
def find_docs_link(link):
# Preserve anchor when doing lookups
link, anchor = link.split('#', 1)
anchor = '#' + anchor
except ValueError:
# No anchor, keep the original link
anchor = ''
for key, val in links_mapping.items():
if re.match(key, link):
return re.sub(key, val, link) + anchor
return None
def transform_github_links(app, doctree, fromdocname):
# Convert relative links in repo into relative links in docs.
# We do this by first figuring out whether the current document
# has been included from outside docs/ and only continue if so.
# Next we take the repo path matching the current document
# (lookup through 'includes_mapping'), tack the link onto the dirname
# of that path and normalize it using os.path.normpath.
# The result is the path to a document/folder in the repo.
# We then convert this path into one that works in the documentation
# (lookup through 'links_mapping').
# If a mapping is found we, create a relative link from the current document.
from docutils import nodes
import os.path
original_path = find_original(fromdocname)
if original_path is None:
for node in doctree.traverse(nodes.reference):
if 'refuri' not in node:
if node['refuri'].startswith('http'):
abs_link = os.path.normpath(os.path.join(os.path.dirname(original_path), node['refuri']))
docs_link = find_docs_link(abs_link)
if docs_link is None:
# special handling for when we link inside the same document
if docs_link.startswith('#'):
node['refuri'] = docs_link
node['refuri'] = os.path.relpath(docs_link, os.path.dirname(fromdocname))