mirror of
https://github.com/vagrant-libvirt/vagrant-libvirt.git
synced 2025-02-25 18:55:27 -06:00
Migrate documentation to github pages (#1523)
Switch from having all documentation contained within the README to publishing a jekyll static site of documentation under github pages. This allows for configuration and installation guides to be handled separately to make for the relevant pieces to be in smaller chunks and therefore easier to follow for users. Additionally a table of contents can now be included in a left navigation section that ensures it should be possible to quickly jump from the start to any section and back again. Include support for publishing previews and releases under separate directories to allow for them to exist at the same time as the other latest version of the documents. The navigation section also includes support for accessing any of the other versions published so that it easier to see what configuration options exist for a given release. These will be published automatically when releases are added.
This commit is contained in:
Darragh Bailey
GitHub
3
docs/_includes/head_custom.html
Normal file
3
docs/_includes/head_custom.html
Normal file
@@ -0,0 +1,3 @@
|
||||
<script src="https://cdnjs.cloudflare.com/ajax/libs/axios/0.27.2/axios.min.js"></script>
|
||||
<link rel="stylesheet" href="{{ '/assets/css/just-the-docs-light.css' | relative_url }}" media="(prefers-color-scheme: light)">
|
||||
<link rel="stylesheet" href="{{ '/assets/css/just-the-docs-dark.css' | relative_url }}" media="(prefers-color-scheme: dark)">
|
||||
6
docs/_includes/header_custom.html
Normal file
6
docs/_includes/header_custom.html
Normal file
@@ -0,0 +1,6 @@
|
||||
<div class="site-footer">
|
||||
Plugin Version:
|
||||
<select id="docs-version" onChange="changeVersion(this)">
|
||||
</select>
|
||||
</div>
|
||||
<script src="{% asset "js/version_switcher.js" @path %}"></script>
|
||||
111
docs/_includes/nav.html
Normal file
111
docs/_includes/nav.html
Normal file
@@ -0,0 +1,111 @@
|
||||
{%- comment -%}
|
||||
Original taken from https://github.com/just-the-docs/just-the-docs/blob/10388ed8b09eeae132a56c2b931e642b5ae2719d/_includes/nav.html
|
||||
{%- endcomment -%}
|
||||
<ul class="nav-list">
|
||||
{%- assign titled_pages = include.pages
|
||||
| where_exp:"item", "item.title != nil" -%}
|
||||
|
||||
{%- comment -%}
|
||||
The values of `title` and `nav_order` can be numbers or strings.
|
||||
Jekyll gives build failures when sorting on mixtures of different types,
|
||||
so numbers and strings need to be sorted separately.
|
||||
|
||||
Here, numbers are sorted by their values, and come before all strings.
|
||||
An omitted `nav_order` value is equivalent to the page's `title` value
|
||||
(except that a numerical `title` value is treated as a string).
|
||||
|
||||
The case-sensitivity of string sorting is determined by `site.nav_sort`.
|
||||
{%- endcomment -%}
|
||||
|
||||
{%- assign string_ordered_pages = titled_pages
|
||||
| where_exp:"item", "item.nav_order == nil" -%}
|
||||
{%- assign nav_ordered_pages = titled_pages
|
||||
| where_exp:"item", "item.nav_order != nil" -%}
|
||||
|
||||
{%- comment -%}
|
||||
The nav_ordered_pages have to be added to number_ordered_pages and
|
||||
string_ordered_pages, depending on the nav_order value.
|
||||
The first character of the jsonify result is `"` only for strings.
|
||||
{%- endcomment -%}
|
||||
{%- assign nav_ordered_groups = nav_ordered_pages
|
||||
| group_by_exp:"item", "item.nav_order | jsonify | slice: 0" -%}
|
||||
{%- assign number_ordered_pages = "" | split:"X" -%}
|
||||
{%- for group in nav_ordered_groups -%}
|
||||
{%- if group.name == '"' -%}
|
||||
{%- assign string_ordered_pages = string_ordered_pages | concat: group.items -%}
|
||||
{%- else -%}
|
||||
{%- assign number_ordered_pages = number_ordered_pages | concat: group.items -%}
|
||||
{%- endif -%}
|
||||
{%- endfor -%}
|
||||
|
||||
{%- assign sorted_number_ordered_pages = number_ordered_pages | sort:"nav_order" -%}
|
||||
|
||||
{%- comment -%}
|
||||
The string_ordered_pages have to be sorted by nav_order, and otherwise title
|
||||
(where appending the empty string to a numeric title converts it to a string).
|
||||
After grouping them by those values, the groups are sorted, then the items
|
||||
of each group are concatenated.
|
||||
{%- endcomment -%}
|
||||
{%- assign string_ordered_groups = string_ordered_pages
|
||||
| group_by_exp:"item", "item.nav_order | default: item.title | append:''" -%}
|
||||
{%- if site.nav_sort == 'case_insensitive' -%}
|
||||
{%- assign sorted_string_ordered_groups = string_ordered_groups | sort_natural:"name" -%}
|
||||
{%- else -%}
|
||||
{%- assign sorted_string_ordered_groups = string_ordered_groups | sort:"name" -%}
|
||||
{%- endif -%}
|
||||
{%- assign sorted_string_ordered_pages = "" | split:"X" -%}
|
||||
{%- for group in sorted_string_ordered_groups -%}
|
||||
{%- assign sorted_string_ordered_pages = sorted_string_ordered_pages | concat: group.items -%}
|
||||
{%- endfor -%}
|
||||
|
||||
{%- assign pages_list = sorted_number_ordered_pages | concat: sorted_string_ordered_pages -%}
|
||||
|
||||
{%- for node in pages_list -%}
|
||||
{%- if node.parent == nil -%}
|
||||
{%- unless node.nav_exclude -%}
|
||||
<li class="nav-list-item{% if page.url == node.url or page.parent == node.title or page.grand_parent == node.title %} active{% endif %}">
|
||||
{%- if node.has_children -%}
|
||||
<a href="#" class="nav-list-expander"><svg viewBox="0 0 24 24"><use xlink:href="#svg-arrow-right"></use></svg></a>
|
||||
{%- endif -%}
|
||||
<a href="{{ node.url | absolute_url }}" class="nav-list-link{% if page.url == node.url %} active{% endif %}">{{ node.title }}</a>
|
||||
{% if page.url == node.url %}
|
||||
{{ content | toc_only }}
|
||||
{% endif %}
|
||||
{%- if node.has_children -%}
|
||||
{%- assign children_list = pages_list | where: "parent", node.title -%}
|
||||
<ul class="nav-list ">
|
||||
{%- for child in children_list -%}
|
||||
{%- unless child.nav_exclude -%}
|
||||
<li class="nav-list-item {% if page.url == child.url or page.parent == child.title %} active{% endif %}">
|
||||
{%- if child.has_children -%}
|
||||
<a href="#" class="nav-list-expander"><svg viewBox="0 0 24 24"><use xlink:href="#svg-arrow-right"></use></svg></a>
|
||||
{%- endif -%}
|
||||
<a href="{{ child.url | absolute_url }}" class="nav-list-link{% if page.url == child.url %} active{% endif %}">{{ child.title }}</a>
|
||||
{% if page.url == child.url %}
|
||||
{{ content | toc_only }}
|
||||
{% endif %}
|
||||
{%- if child.has_children -%}
|
||||
{%- assign grand_children_list = pages_list | where: "parent", child.title | where: "grand_parent", node.title -%}
|
||||
<ul class="nav-list">
|
||||
{%- for grand_child in grand_children_list -%}
|
||||
{%- unless grand_child.nav_exclude -%}
|
||||
<li class="nav-list-item {% if page.url == grand_child.url %} active{% endif %}">
|
||||
<a href="{{ grand_child.url | absolute_url }}" class="nav-list-link{% if page.url == grand_child.url %} active{% endif %}">{{ grand_child.title }}</a>
|
||||
{% if page.url == grand_child.url %}
|
||||
{{ content | toc_only }}
|
||||
{% endif %}
|
||||
</li>
|
||||
{%- endunless -%}
|
||||
{%- endfor -%}
|
||||
</ul>
|
||||
{%- endif -%}
|
||||
</li>
|
||||
{%- endunless -%}
|
||||
{%- endfor -%}
|
||||
</ul>
|
||||
{%- endif -%}
|
||||
</li>
|
||||
{%- endunless -%}
|
||||
{%- endif -%}
|
||||
{%- endfor -%}
|
||||
</ul>
|
||||
97
docs/_includes/patch-vagrant-install.html
Normal file
97
docs/_includes/patch-vagrant-install.html
Normal file
@@ -0,0 +1,97 @@
|
||||
libssh issue:
|
||||
```
|
||||
/opt/vagrant/embedded/lib/ruby/2.4.0/rubygems/core_ext/kernel_require.rb:55:in `require': /opt/vagrant/embedded/lib64/libcrypto.so.1.1: version `OPENSSL_1_1_1b' not found (required by /lib64/libssh.so.4) - /home/xxx/.vagrant.d/gems/2.4.6/gems/ruby-libvirt-0.7.1/lib/_libvirt.so (LoadError)
|
||||
```
|
||||
Solution identified thanks to James Reynolds (see [https://github.com/hashicorp/vagrant/issues/11020#issuecomment-540043472](https://github.com/hashicorp/vagrant/issues/11020#issuecomment-540043472)).
|
||||
|
||||
libk5crypto issue:
|
||||
```
|
||||
/opt/vagrant/embedded/lib/ruby/2.4.0/rubygems/core_ext/kernel_require.rb:55:in `require': /usr/lib64/libk5crypto.so.3: undefined symbol: EVP_KDF_ctrl, version OPENSSL_1_1_1b - /home/rbelgrave/.vagrant.d/gems/2.4.9/gems/ruby-libvirt-0.7.1/lib/_libvirt.so (LoadError)
|
||||
```
|
||||
Solution identified thanks to Marco Bevc (see [https://github.com/hashicorp/vagrant/issues/11020#issuecomment-625801983](https://github.com/hashicorp/vagrant/issues/11020#issuecomment-625801983)).
|
||||
|
||||
Compile libraries to replaced those bundled with Vagrant to allow linking ruby-libvirt against
|
||||
vagrant's embedded ruby and the system libvirt (updated originals to be generic):
|
||||
|
||||
```bash
|
||||
mkdir patches
|
||||
pushd patches
|
||||
{%- if include.distro == "centos" or include.distro == "rhel" %}
|
||||
|
||||
[[ ! -d centos-git-common ]] && git clone https://git.centos.org/centos-git-common
|
||||
export PATH=$(readlink -f ./centos-git-common):$PATH
|
||||
chmod a+x ./centos-git-common/*.sh
|
||||
|
||||
git clone https://git.centos.org/rpms/libssh
|
||||
{%- else %}
|
||||
|
||||
mkdir libssh
|
||||
{%- endif %}
|
||||
pushd libssh
|
||||
nvr=$(rpm -q --queryformat "libssh-%{version}-%{release}" libssh)
|
||||
nv=$(rpm -q --queryformat "libssh-%{version}" libssh)
|
||||
{%- if include.distro == "fedora" %}
|
||||
dnf download --source libssh
|
||||
rpm2cpio ${nvr}.src.rpm | cpio -imdV
|
||||
rm -rf ${nv}
|
||||
tar xf ${nv}.tar.*z
|
||||
{%- elsif include.distro == "centos" %}
|
||||
git checkout $(git tag -l | grep "${nvr}\$" | tail -n1)
|
||||
into_srpm.sh -d c8s
|
||||
pushd BUILD
|
||||
tar xf ../SOURCES/${nv}.tar.*z
|
||||
{%- elsif include.distro == "opensuse" %}
|
||||
{%- else %}
|
||||
|
||||
*******Missing the correct distro for patch commands********
|
||||
{%- endif %}
|
||||
|
||||
mkdir libssh-build
|
||||
pushd libssh-build
|
||||
cmake ../${nv} -DOPENSSL_ROOT_DIR=/opt/vagrant/embedded/
|
||||
make
|
||||
sudo cp lib/libssh* /opt/vagrant/embedded/lib64
|
||||
popd
|
||||
popd
|
||||
{%- if include.distro == "centos" %}
|
||||
|
||||
popd
|
||||
{%- endif %}
|
||||
|
||||
{%- if include.distro == "centos" or include.distro == "rhel" %}
|
||||
|
||||
git clone https://git.centos.org/rpms/krb5
|
||||
{%- else %}
|
||||
|
||||
mkdir krb5
|
||||
{%- endif %}
|
||||
pushd krb5
|
||||
nvr=$(rpm -q --queryformat "krb5-%{version}-%{release}" krb5-libs)
|
||||
nv=$(rpm -q --queryformat "krb5-%{version}" krb5-libs)
|
||||
{%- if include.distro == "fedora" %}
|
||||
dnf download --source krb5-libs
|
||||
rpm2cpio ${nvr}.src.rpm | cpio -imdV
|
||||
tar xf ${nv}.tar.*z
|
||||
{%- elsif include.distro == "centos" %}
|
||||
git checkout $(git tag -l | grep "${nvr}\$" | tail -n1)
|
||||
into_srpm.sh -d c8s
|
||||
pushd BUILD
|
||||
tar xf ../SOURCES/${nv}.tar.*z
|
||||
{%- elsif include.distro == "opensuse" %}
|
||||
{%- else %}
|
||||
*******Missing the correct distro for patch commands********
|
||||
{%- endif %}
|
||||
|
||||
pushd ${nv}/src
|
||||
./configure
|
||||
make
|
||||
sudo cp -P lib/crypto/libk5crypto.* /opt/vagrant/embedded/lib64/
|
||||
popd
|
||||
popd
|
||||
{%- if include.distro == "centos" %}
|
||||
|
||||
popd
|
||||
{%- endif %}
|
||||
|
||||
popd
|
||||
```
|
||||
4
docs/_includes/title.html
Normal file
4
docs/_includes/title.html
Normal file
@@ -0,0 +1,4 @@
|
||||
{% if site.logo %}
|
||||
<div class="site-logo"></div>
|
||||
{% endif %}
|
||||
{{ site.title }}
|
||||
42
docs/_includes/upstream-vagrant-install.html
Normal file
42
docs/_includes/upstream-vagrant-install.html
Normal file
@@ -0,0 +1,42 @@
|
||||
* Upstream Vagrant Install<br />
|
||||
Download and execute the vagrant-libvirt-qa install script (installs latest vagrant by default):
|
||||
```shell
|
||||
curl -O https://github.com/vagrant-libvirt/vagrant-libvirt-qa/blob/main/scripts/install.bash
|
||||
chmod a+x ./install.bash
|
||||
./install.bash
|
||||
```
|
||||
* Alternatively install vagrant following [https://www.vagrantup.com/downloads](https://www.vagrantup.com/downloads):
|
||||
{% if include.distro == "debian" or include.distro == "ubuntu" -%}
|
||||
```shell
|
||||
curl -fsSL https://apt.releases.hashicorp.com/gpg | sudo apt-key add -
|
||||
sudo apt-add-repository "deb [arch=amd64] https://apt.releases.hashicorp.com $(lsb_release -cs) main"
|
||||
sudo apt-get update && sudo apt-get install vagrant
|
||||
```
|
||||
{% elsif include.distro == "fedora" -%}
|
||||
```shell
|
||||
sudo dnf install -y dnf-plugins-core
|
||||
sudo dnf config-manager --add-repo https://rpm.releases.hashicorp.com/fedora/hashicorp.repo
|
||||
sudo dnf -y install vagrant
|
||||
```
|
||||
{% elsif include.distro == "centos" or include.distro == "rhel" -%}
|
||||
```shell
|
||||
sudo yum install -y yum-utils
|
||||
sudo yum-config-manager --add-repo https://rpm.releases.hashicorp.com/RHEL/hashicorp.repo
|
||||
sudo yum -y install vagrant
|
||||
```
|
||||
{% elsif include.distro == "opensuse" %}
|
||||
As there is no upstream repository this will not be kept up to date automatically.
|
||||
{: .warn }
|
||||
|
||||
```shell
|
||||
version="$(
|
||||
wget -qO - https://checkpoint-api.hashicorp.com/v1/check/vagrant 2>/dev/null | \
|
||||
tr ',' '\n' | grep current_version | cut -d: -f2 | tr -d '"'
|
||||
)"
|
||||
wget --no-verbose -O vagrant.rpm \
|
||||
https://releases.hashicorp.com/vagrant/${version}/vagrant_${version}_x86_64.rpm
|
||||
sudo zypper install --allow-unsigned-rpm --no-confirm vagrant.rpm
|
||||
```
|
||||
{% else -%}
|
||||
Missing the correct distro for vagrant install in site generation
|
||||
{% endif -%}
|
||||
Reference in New Issue
Block a user