From 501e6ad97bf471c2905d77debbd43d5956af1152 Mon Sep 17 00:00:00 2001 From: Anders Ingemann Date: Sun, 19 Apr 2015 13:05:58 +0200 Subject: [PATCH] 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 +- README.rst | 16 ++-- bootstrapvz/providers/ec2/README.rst | 2 +- bootstrapvz/providers/virtualbox/README.rst | 2 +- docs/conf.py | 14 ++-- docs/replace_rtd_links.py | 89 +++++++++++++++++++-- manifests/README.rst | 8 +- 7 files changed, 107 insertions(+), 30 deletions(-) diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index 9c853f5..d5ab31a 100644 --- a/CONTRIBUTING.rst +++ b/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 `__ ++ Read the `development guidelines <#development-guidelines>`__ + Fork this repository. + Make any changes you want/need. + Check the coding style of your changes using `tox `__ 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 `__ 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 `__. + add your name and contribution to the `changelog `__. + 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 - `__ + `__ 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). diff --git a/README.rst b/README.rst index 5df80d6..8b47a45 100644 --- a/README.rst +++ b/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 `__ +`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 `__. There, you can discover `what the -dependencies `__ +dependencies <#dependencies>`__ for a specific cloud provider are, `see a list of available -plugins `__ and +plugins `__ and learn `how you create a -manifest `__. +manifest `__. 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 `__ +If you want to use the `minimize\_size `__ plugin, you will have to install the ``zerofree`` package and `VMWare Workstation `__ as well. @@ -113,7 +113,7 @@ Dependencies ------------ bootstrap-vz has a number of dependencies depending on the target -platform and `the selected plugins `__. +platform and `the selected plugins `__. At a bare minimum the following python libraries are needed: * `termcolor `__ @@ -142,7 +142,7 @@ Contributing ------------ Contribution guidelines are described in the documentation under -`Contributing `__. +`Contributing `__. There's also -`a topic `__ +`a topic `__ regarding the coding style. diff --git a/bootstrapvz/providers/ec2/README.rst b/bootstrapvz/providers/ec2/README.rst index 05b63e8..c968f48 100644 --- a/bootstrapvz/providers/ec2/README.rst +++ b/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 `__ +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 diff --git a/bootstrapvz/providers/virtualbox/README.rst b/bootstrapvz/providers/virtualbox/README.rst index 154199b..37300ff 100644 --- a/bootstrapvz/providers/virtualbox/README.rst +++ b/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 `__. +manifest <../../../manifests#bootstrapper>`__. diff --git a/docs/conf.py b/docs/conf.py index f6deef4..b43fedd 100644 --- a/docs/conf.py +++ b/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 -------------------------------------- diff --git a/docs/replace_rtd_links.py b/docs/replace_rtd_links.py index c18d1c4..1303d9f 100644 --- a/docs/replace_rtd_links.py +++ b/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)) diff --git a/manifests/README.rst b/manifests/README.rst index d644979..df598a3 100644 --- a/manifests/README.rst +++ b/manifests/README.rst @@ -39,7 +39,7 @@ name of the provider itself. - **``name``**: target virtualization platform of the installation *``required``* -Consult the `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 `__. + `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 `__ 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 `__ +plugin requires. Go to the `plugin section <../bootstrapvz/plugins>`__ of the documentation, to see the configuration for a specific plugin.