This is cool. Relative links that link between folders/files in the github repo are converted to relative links in the documentation.

CONTRIBUTING.rst

@@ -6,7 +6,7 @@ Sending pull requests
 
 Do you want to contribute to the bootstrap-vz project? Nice! Here is the basic workflow:
 
-+ Read the `development guidelines <http://bootstrap-vz.readthedocs.org/en/master/contributing.html#development-guidelines>`__
++ Read the `development guidelines <#development-guidelines>`__
 + Fork this repository.
 + Make any changes you want/need.
 + Check the coding style of your changes using `tox <http://tox.readthedocs.org/>`__ by running `tox -e flake8`
@@ -14,7 +14,7 @@ Do you want to contribute to the bootstrap-vz project? Nice! Here is the basic w
   This check will be repeated by `Travis CI <https://travis-ci.org/andsens/bootstrap-vz>`__
   once you send a pull request, so it's better if you check this beforehand.
 + If the change is significant (e.g. a new plugin, manifest setting or security fix)
-  add your name and contribution to the `changelog <http://bootstrap-vz.readthedocs.org/en/master/changelog.html>`__.
+  add your name and contribution to the `changelog <CHANGELOG.rst>`__.
 + Commit your changes.
 + Squash the commits if needed. For instance, it is fine if you have multiple commits describing atomic units
   of work, but there's no reason to have many little commits just because of corrected typos.
@@ -107,7 +107,7 @@ value to the bootstrap-vz codebase.
   This allows other tasks to interleave with the control-flow and add extended
   functionality (e.g. because volume creation and mounting are two
   separate tasks, `the prebootstrapped plugin
-  <http://bootstrap-vz.readthedocs.org/en/master/plugins/prebootstrapped.html>`__
+  <bootstrapvz/plugins/prebootstrapped>`__
   can replace the volume creation task with a task of its own that
   creates a volume from a snapshot instead, but still reuse the mount task).
 

README.rst

@@ -7,7 +7,7 @@ bootstrap-vz runs without any user intervention and
 generates ready-to-boot images for a number of virtualization
 platforms.
 Its aim is to provide a reproducable bootstrapping process using
-`manifests <http://bootstrap-vz.readthedocs.org/en/master/manifest.html>`__
+`manifests <manifests>`__
 as well as supporting a high degree of customizability through plugins.
 
 bootstrap-vz was coded from scratch in python once the bash script
@@ -21,11 +21,11 @@ Documentation
 The documentation for bootstrap-vz is available at
 `bootstrap-vz.readthedocs.org <http://bootstrap-vz.readthedocs.org/en/master>`__.
 There, you can discover `what the
-dependencies <http://bootstrap-vz.readthedocs.org/en/master/index.html#dependencies>`__
+dependencies <#dependencies>`__
 for a specific cloud provider are, `see a list of available
-plugins <http://bootstrap-vz.readthedocs.org/en/master/plugins>`__ and
+plugins <bootstrapvz/plugins>`__ and
 learn `how you create a
-manifest <http://bootstrap-vz.readthedocs.org/en/master/manifest.html>`__.
+manifest <manifests>`__.
 
 Installation
 ------------
@@ -68,7 +68,7 @@ VirtualBox Vagrant
     root@host:~# pip install termcolor jsonschema fysom docopt pyyaml # Install python dependencies
     root@host:~# bootstrap-vz/bootstrap-vz bootstrap-vz/manifests/virtualbox-vagrant.manifest.yml
 
-If you want to use the `minimize\_size <http://bootstrap-vz.readthedocs.org/en/master/plugins/minimize_size.html>`__
+If you want to use the `minimize\_size <bootstrapvz/plugins/minimize_size>`__
 plugin, you will have to install the ``zerofree`` package and `VMWare
 Workstation <https://my.vmware.com/web/vmware/info/slug/desktop_end_user_computing/vmware_workstation/10_0>`__
 as well.
@@ -113,7 +113,7 @@ Dependencies
 ------------
 
 bootstrap-vz has a number of dependencies depending on the target
-platform and `the selected plugins <http://bootstrap-vz.readthedocs.org/en/master/plugins>`__.
+platform and `the selected plugins <bootstrapvz/plugins>`__.
 At a bare minimum the following python libraries are needed:
 
 * `termcolor <https://pypi.python.org/pypi/termcolor>`__
@@ -142,7 +142,7 @@ Contributing
 ------------
 
 Contribution guidelines are described in the documentation under
-`Contributing <http://bootstrap-vz.readthedocs.org/en/master/developers/contributing.html>`__.
+`Contributing <CONTRIBUTING.rst>`__.
 There's also
-`a topic <http://bootstrap-vz.readthedocs.org/en/master/developers/contributing.html#coding-style>`__
+`a topic <CONTRIBUTING.rst#coding-style>`__
 regarding the coding style.

bootstrapvz/providers/ec2/README.rst

@@ -7,7 +7,7 @@ once it is done and registers it as an AMI. EBS volume backing only
 works on an EC2 host while S3 backed volumes *should* work locally (at
 this time however they do not, a fix is in the works).
 
-Unless `the cloud-init plugin <http://bootstrap-vz.readthedocs.org/en/master/plugins/cloud_init.html>`__
+Unless `the cloud-init plugin <../../plugins/cloud_init>`__
 is used, special startup scripts will be installed that automatically fetch the
 configured authorized\_key from the instance metadata and save or run
 any userdata supplied (if the userdata begins with ``#!`` it will be

bootstrapvz/providers/virtualbox/README.rst

@@ -9,4 +9,4 @@ interoperability (e.g.
 *should* support vdi files, but since they have no identifier URL not
 even VirtualBox itself can import them). VirtualBox Guest Additions can
 be installed automatically if the ISO is `provided in the
-manifest <http://bootstrap-vz.readthedocs.org/en/master/manifest.html#bootstrapper>`__.
+manifest <../../../manifests#bootstrapper>`__.

docs/conf.py

@@ -272,17 +272,19 @@ import os.path
 for readme_path in glob.glob('../bootstrapvz/providers/*/README.rst'):
 	provider_name = os.path.basename(os.path.dirname(readme_path))
 	include_path = os.path.join('providers', provider_name + '.rst')
-	path_to_readme = os.path.join('../../bootstrapvz/providers', provider_name, 'README.rst')
-	with open(include_path, 'w') as include:
-		include.write('.. include:: ' + path_to_readme)
+	if not os.path.exists(include_path):
+		path_to_readme = os.path.join('../../bootstrapvz/providers', provider_name, 'README.rst')
+		with open(include_path, 'w') as include:
+			include.write('.. include:: ' + path_to_readme)
 
 
 for readme_path in glob.glob('../bootstrapvz/plugins/*/README.rst'):
 	plugin_name = os.path.basename(os.path.dirname(readme_path))
 	include_path = os.path.join('plugins', plugin_name + '.rst')
-	path_to_readme = os.path.join('../../bootstrapvz/plugins', plugin_name, 'README.rst')
-	with open(include_path, 'w') as include:
-		include.write('.. include:: ' + path_to_readme)
+	if not os.path.exists(include_path):
+		path_to_readme = os.path.join('../../bootstrapvz/plugins', plugin_name, 'README.rst')
+		with open(include_path, 'w') as include:
+			include.write('.. include:: ' + path_to_readme)
 
 
 # -- Create task overview graph data --------------------------------------

docs/replace_rtd_links.py

@@ -1,19 +1,94 @@
+import re
+
 
 def setup(app):
 	app.connect('doctree-resolved', replace_rtd_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'^manifest$': r'manifests/',
+	r'^testing/index$': r'testing/',
+	r'^testing/(?!index)([^/]+)_tests$': r'testing/\1/',
+	r'^remote_bootstrapping$': r'bootstrapvz/remote/',
+	r'^developers/index$': r'bootstrapvz/',
+	r'^developers/contributing$': r'CONTRIBUTING.rst',
+	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'^testing$': r'testing',
+	r'^manifests$': r'manifest.html',
+	r'^testing/([^/]+)$': r'testing/\1_tests.html',
+	r'^bootstrapvz/remote$': r'remote_bootstrapping.html',
+	r'^bootstrapvz$': r'developers',
+	r'^CONTRIBUTING\.rst$': r'developers/contributing.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):
+	try:
+		# 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 replace_rtd_links(app, doctree, fromdocname):
-	from docutils import nodes
-	import re
+	# 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:
+		return
 
-	rtd_baseurl = 'http://bootstrap-vz.readthedocs.org/en/master/'
-	search = re.compile('^' + re.escape(rtd_baseurl) + '(.*)$')
 	for node in doctree.traverse(nodes.reference):
 		if 'refuri' not in node:
 			continue
-		if not node['refuri'].startswith(rtd_baseurl):
+		if node['refuri'].startswith('http'):
 			continue
-		node['refuri'] = re.sub(search, r'\1', node['refuri'])
+		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:
+			continue
+		node['refuri'] = os.path.relpath(docs_link, os.path.dirname(fromdocname))

manifests/README.rst

@@ -39,7 +39,7 @@ name of the provider itself.
 -  **``name``**: target virtualization platform of the installation
    *``required``*
 
-Consult the `providers <http://bootstrap-vz.readthedocs.org/en/master/providers>`__ section of the documentation
+Consult the `providers <../bootstrapvz/providers>`__ section of the documentation
 for a list of valid values.
 
 Bootstrapper
@@ -76,7 +76,7 @@ are 4 possible settings:
    Accepts a list of package names.
    *``optional``*
 -  **``guest_additions``**: This setting is only relevant for the
-   `virtualbox provider <http://bootstrap-vz.readthedocs.org/en/master/providers/virtualbox.html>`__.
+   `virtualbox provider <../bootstrapvz/providers/virtualbox.html>`__.
    It specifies the path to the VirtualBox Guest Additions ISO, which, when specified,
    will be mounted and used to install the VirtualBox Guest Additions.
    *``optional``*
@@ -216,7 +216,7 @@ boot, root and swap.
       optional setting overrides the command bootstrap-vz would normally
       use to format the partition. The command is specified as a string
       array where each option/argument is an item in that array (much
-      like the `image\_commands <http://bootstrap-vz.readthedocs.org/en/master/plugins/image_commands.html>`__ plugin).
+      like the `image\_commands <../bootstrapvz/plugins/image_commands.html>`__ plugin).
       *``optional``* The following variables are available:
    -  **``{fs}``**: The filesystem of the partition.
    -  **``{device_path}``**: The device path of the partition.
@@ -237,5 +237,5 @@ Plugins
 ~~~~~~~
 
 The plugins section is a map of plugin names to whatever configuration a
-plugin requires. Go to the `plugin section <http://bootstrap-vz.readthedocs.org/en/master/plugins>`__
+plugin requires. Go to the `plugin section <../bootstrapvz/plugins>`__
 of the documentation, to see the configuration for a specific plugin.