Support global link definitions.

Works by symlinking the global.rst which is included in this repo to all
submodules which have a `docs/includes` directory in them. This allows
to update the definition in on central place.

Wrote scripts to generate:

* Ansible modules
* DebOps roles (likes to GitHub repo)
* DebOps Contrib roles (likes to GitHub repo)
* ypid roles (likes to GitHub repo, seamless self plug. Added my private Ansible roles for reference.)

Usage for roles (or other DebOps repos):

Create `./docs/includes/all.rst`:
```rst
.. include:: includes/global.rst
```

Ensure line present in `.gitignore`:
```rst
docs/includes/global.rst
```

Optional: copy https://github.com/debops/docs/tree/master/docs/includes/global.rst
to `docs/includes/global.rst`
(Only needed when the repos should be build as standalone for testing.)

Use in docs like so (example `docs/getting-started.rst`):
```rst
Getting started
===============

.. contents::
   :local:

.. include:: includes/all.rst

DebOps_ rocks!
..    ↑ makes it a hyperlink.
```

Thats should be all. Enjoy 😉

Implements: debops#155

docs/Makefile

@@ -48,39 +48,69 @@ help:
 
 clean:
 	rm -rf $(BUILDDIR)/*
+	rm -rf includes/*gen_*
 
-html:
+.PHONY: FORCE_MAKE
+
+prepare: includes/global.rst linkincludes
+
+includes/global.rst: \
+		includes/30gen_ansible_modules.rst \
+		includes/40gen_debops_repos.rst \
+		includes/45gen_debops_repos.rst \
+		includes/60gen_ypid_repos.rst \
+		Makefile
+	run-parts --list --regex '.*\.rst' includes | grep -v 'global.rst$$' | xargs awk 'FNR==1{print ""}{print}' > "$@"
+
+includes/30gen_ansible_modules.rst: ./bin/gen_ansible_modules_rst_defs
+	"$<" > "$@"
+
+includes/40gen_debops_repos.rst: ./bin/gen_rst_defs_using_remote_api
+	"$<" > "$@" 'github' 'DebOps' 'debops' 'orgs'
+
+includes/45gen_debops_repos.rst: ./bin/gen_rst_defs_using_remote_api
+	"$<" > "$@" 'github' 'DebOps Contrib' 'debops-contrib' 'orgs'
+
+includes/60gen_ypid_repos.rst: ./bin/gen_rst_defs_using_remote_api
+	"$<" > "$@" 'github' 'ypid' 'ypid' 'users'
+
+.PHONY: linkincludes
+linkincludes:
+	./bin/linkincludes
+
+
+html: prepare
 	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
 	@echo
 	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
 
-dirhtml:
+dirhtml: prepare
 	$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
 	@echo
 	@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
 
-singlehtml:
+singlehtml: prepare
 	$(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
 	@echo
 	@echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
 
-pickle:
+pickle: prepare
 	$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
 	@echo
 	@echo "Build finished; now you can process the pickle files."
 
-json:
+json: prepare
 	$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
 	@echo
 	@echo "Build finished; now you can process the JSON files."
 
-htmlhelp:
+htmlhelp: prepare
 	$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
 	@echo
 	@echo "Build finished; now you can run HTML Help Workshop with the" \
 	      ".hhp project file in $(BUILDDIR)/htmlhelp."
 
-qthelp:
+qthelp: prepare
 	$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
 	@echo
 	@echo "Build finished; now you can run "qcollectiongenerator" with the" \
@@ -89,7 +119,7 @@ qthelp:
 	@echo "To view the help file:"
 	@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/DebOps.qhc"
 
-devhelp:
+devhelp: prepare
 	$(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
 	@echo
 	@echo "Build finished."
@@ -98,80 +128,80 @@ devhelp:
 	@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/DebOps"
 	@echo "# devhelp"
 
-epub:
+epub: prepare
 	$(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
 	@echo
 	@echo "Build finished. The epub file is in $(BUILDDIR)/epub."
 
-latex:
+latex: prepare
 	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
 	@echo
 	@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
 	@echo "Run \`make' in that directory to run these through (pdf)latex" \
 	      "(use \`make latexpdf' here to do that automatically)."
 
-latexpdf:
+latexpdf: prepare
 	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
 	@echo "Running LaTeX files through pdflatex..."
 	$(MAKE) -C $(BUILDDIR)/latex all-pdf
 	@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
 
-latexpdfja:
+latexpdfja: prepare
 	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
 	@echo "Running LaTeX files through platex and dvipdfmx..."
 	$(MAKE) -C $(BUILDDIR)/latex all-pdf-ja
 	@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
 
-text:
+text: prepare
 	$(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
 	@echo
 	@echo "Build finished. The text files are in $(BUILDDIR)/text."
 
-man:
+man: prepare
 	$(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man
 	@echo
 	@echo "Build finished. The manual pages are in $(BUILDDIR)/man."
 
-texinfo:
+texinfo: prepare
 	$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
 	@echo
 	@echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo."
 	@echo "Run \`make' in that directory to run these through makeinfo" \
 	      "(use \`make info' here to do that automatically)."
 
-info:
+info: prepare
 	$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
 	@echo "Running Texinfo files through makeinfo..."
 	make -C $(BUILDDIR)/texinfo info
 	@echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo."
 
-gettext:
+gettext: prepare
 	$(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale
 	@echo
 	@echo "Build finished. The message catalogs are in $(BUILDDIR)/locale."
 
-changes:
+changes: prepare
 	$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
 	@echo
 	@echo "The overview file is in $(BUILDDIR)/changes."
 
-linkcheck:
+linkcheck: prepare
 	$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
 	@echo
 	@echo "Link check complete; look for any errors in the above output " \
 	      "or in $(BUILDDIR)/linkcheck/output.txt."
 
-doctest:
+doctest: prepare
 	$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
 	@echo "Testing of doctests in the sources finished, look at the " \
 	      "results in $(BUILDDIR)/doctest/output.txt."
 
-xml:
+xml: prepare
 	$(SPHINXBUILD) -b xml $(ALLSPHINXOPTS) $(BUILDDIR)/xml
 	@echo
 	@echo "Build finished. The XML files are in $(BUILDDIR)/xml."
 
-pseudoxml:
+pseudoxml: prepare
 	$(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml
 	@echo
 	@echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml."

docs/bin/gen_ansible_modules_rst_defs

@@ -0,0 +1,27 @@
+#!/bin/bash
+## @author Copyright (C) 2016 Robin Schneider <ypid@riseup.net>
+## @license GPL-3.0 <https://www.gnu.org/licenses/gpl-3.0.html>
+
+## Generate URL definitions of all Ansible modules in RST.
+
+set -e
+
+echo '.. Ansible modules [[[
+.. This section was generated by: https://github.com/debops/docs/blob/master/docs/docs/bin/gen_ansible_modules_rst_defs
+'
+
+## dev/testing: `ansible-doc -l` needs to be cached because it is that freaking slow.
+# test -f "/tmp/ansible_module.list" || ansible-doc -l 2>/dev/null > "/tmp/ansible_module.list"
+# cut -d ' ' -f 1 "/tmp/ansible_module.list" | while read -r ansible_module_name
+
+ansible-doc -l 2>/dev/null | cut -d ' ' -f 1 | while read -r ansible_module_name
+do
+    if [[ "$ansible_module_name" == "DEPRECATED:" ]]
+    then
+        echo "Deprecated modules follow:"
+    else
+        echo ".. _Ansible ${ansible_module_name} module: https://docs.ansible.com/ansible/${ansible_module_name}_module.html"
+    fi
+done
+
+echo '.. ]]]'

docs/bin/gen_rst_defs_using_remote_api

@@ -0,0 +1,49 @@
+#!/bin/bash
+## @author Copyright (C) 2016 Robin Schneider <ypid@riseup.net>
+## @license GPL-3.0 <https://www.gnu.handle/licenses/gpl-3.0.html>
+
+## Generate URL definitions based on data returned by remote API.
+
+set -e
+
+SCRIPT_URL='https://github.com/debops/docs/blob/master/docs/docs/bin/gen_rst_defs_using_remote_api'
+
+get_defs_by_github_api_call() {
+    ## Ref: https://developer.github.com/v3/repos/#list-user-repositories
+    handle_name="$1"
+    handle_id="$2";
+
+    ## Choices: orgs, users
+    mode="${3:-orgs}"
+
+    github_api_url="https://api.github.com/$mode/$handle_id/repos"
+    # echo "$github_api_url"
+    test -f "/tmp/${handle_id}.json" || curl --silent "$github_api_url" > "/tmp/${handle_id}.json"
+
+    echo ".. $handle_name repositories [[["
+    echo ".. This section was generated by: $SCRIPT_URL"
+    echo ""
+
+    jq --raw-output '.[].name' "/tmp/${handle_id}.json" | while read -r repo_name
+    do
+        case $repo_name in
+            ansible-*)
+                role_name="${repo_name#ansible-}"
+                if [[ $role_name =~ .*-.* ]]
+                then
+                    ## Don’t include roles with legacy naming scheme.
+                    continue
+                fi
+                echo ".. _${handle_id}.${role_name}: https://github.com/$handle_id/$repo_name"
+                ;;
+        esac
+    done
+
+    echo '.. ]]]'
+}
+
+case $1 in
+    github)
+        get_defs_by_github_api_call "$2" "$3" "$4"
+        ;;
+esac

docs/bin/linkincludes

@@ -0,0 +1,20 @@
+#!/bin/bash
+## @author Copyright (C) 2016 Robin Schneider <ypid@riseup.net>
+## @license GPL-3.0 <https://www.gnu.org/licenses/gpl-3.0.html>
+
+## Link the global.rst include file into all parts of DebOps which use it.
+
+set -e
+
+test -f "includes/global.rst" || exit 1
+
+DOCS_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )/.." && pwd )"
+
+find . -type d -iwholename '.*docs/includes' | while read -r target_include_dir
+do
+    pushd "$target_include_dir" 1>/dev/null
+    ln -rsf "$DOCS_DIR/includes/global.rst" global.rst
+    popd
+    ## Print for debugging for now.
+    # 1>/dev/null
+done

docs/includes/10pre.rst

@@ -0,0 +1,9 @@
+.. vim: foldmarker=[[[,]]]:foldmethod=marker
+.. Generated by the scripts contained in https://github.com/debops/docs/tree/master/docs/includes/global.rst
+.. This file is possible copied to multiple git repositories.
+
+.. Ansible core [[[
+
+.. _Ansible: https://www.ansible.com/
+
+.. ]]]

docs/includes/40gen_debops_repos.rst

@@ -0,0 +1,29 @@
+.. DebOps repositories [[[
+.. This section was generated by: https://github.com/debops/docs/blob/master/docs/docs/bin/gen_rst_defs_using_remote_api
+
+.. _debops.secret: https://github.com/debops/ansible-secret
+.. _debops.apt: https://github.com/debops/ansible-apt
+.. _debops.apt_preferences: https://github.com/debops/ansible-apt_preferences
+.. _debops.auth: https://github.com/debops/ansible-auth
+.. _debops.backporter: https://github.com/debops/ansible-backporter
+.. _debops.boxbackup: https://github.com/debops/ansible-boxbackup
+.. _debops.console: https://github.com/debops/ansible-console
+.. _debops.debops: https://github.com/debops/ansible-debops
+.. _debops.debug: https://github.com/debops/ansible-debug
+.. _debops.dhcpd: https://github.com/debops/ansible-dhcpd
+.. _debops.directories: https://github.com/debops/ansible-directories
+.. _debops.dnsmasq: https://github.com/debops/ansible-dnsmasq
+.. _debops.encfs: https://github.com/debops/ansible-encfs
+.. _debops.etc_services: https://github.com/debops/ansible-etc_services
+.. _debops.etherpad: https://github.com/debops/ansible-etherpad
+.. _debops.ferm: https://github.com/debops/ansible-ferm
+.. _debops.gitlab: https://github.com/debops/ansible-gitlab
+.. _debops.gitlab_ci: https://github.com/debops/ansible-gitlab_ci
+.. _debops.gitlab_ci_runner: https://github.com/debops/ansible-gitlab_ci_runner
+.. _debops.gitusers: https://github.com/debops/ansible-gitusers
+.. _debops.ifupdown: https://github.com/debops/ansible-ifupdown
+.. _debops.java: https://github.com/debops/ansible-java
+.. _debops.kvm: https://github.com/debops/ansible-kvm
+.. _debops.lxc: https://github.com/debops/ansible-lxc
+.. _debops.mailman: https://github.com/debops/ansible-mailman
+.. ]]]

docs/includes/45gen_debops_repos.rst

@@ -0,0 +1,22 @@
+.. DebOps Contrib repositories [[[
+.. This section was generated by: https://github.com/debops/docs/blob/master/docs/docs/bin/gen_rst_defs_using_remote_api
+
+.. _debops-contrib.openvpn: https://github.com/debops-contrib/ansible-openvpn
+.. _debops-contrib.nullmailer: https://github.com/debops-contrib/ansible-nullmailer
+.. _debops-contrib.apparmor: https://github.com/debops-contrib/ansible-apparmor
+.. _debops-contrib.snapshot_snapper: https://github.com/debops-contrib/ansible-snapshot_snapper
+.. _debops-contrib.roundcube: https://github.com/debops-contrib/ansible-roundcube
+.. _debops-contrib.checkmk_agent: https://github.com/debops-contrib/ansible-checkmk_agent
+.. _debops-contrib.lam: https://github.com/debops-contrib/ansible-lam
+.. _debops-contrib.foodsoft: https://github.com/debops-contrib/ansible-foodsoft
+.. _debops-contrib.collectd: https://github.com/debops-contrib/ansible-collectd
+.. _debops-contrib.influxdb_server: https://github.com/debops-contrib/ansible-influxdb_server
+.. _debops-contrib.sentry: https://github.com/debops-contrib/ansible-sentry
+.. _debops-contrib.influxdb: https://github.com/debops-contrib/ansible-influxdb
+.. _debops-contrib.varnish: https://github.com/debops-contrib/ansible-varnish
+.. _debops-contrib.etckeeper: https://github.com/debops-contrib/ansible-etckeeper
+.. _debops-contrib.fuse: https://github.com/debops-contrib/ansible-fuse
+.. _debops-contrib.checkmk_server: https://github.com/debops-contrib/ansible-checkmk_server
+.. _debops-contrib.btrfs: https://github.com/debops-contrib/ansible-btrfs
+.. _debops-contrib.x2go_server: https://github.com/debops-contrib/ansible-x2go_server
+.. ]]]

docs/includes/60gen_ypid_repos.rst

@@ -0,0 +1,27 @@
+.. ypid repositories [[[
+.. This section was generated by: https://github.com/debops/docs/blob/master/docs/docs/bin/gen_rst_defs_using_remote_api
+
+.. _ypid.apparmor: https://github.com/ypid/ansible-apparmor
+.. _ypid.apt: https://github.com/ypid/ansible-apt
+.. _ypid.apt_cacher_ng: https://github.com/ypid/ansible-apt_cacher_ng
+.. _ypid.apt_install: https://github.com/ypid/ansible-apt_install
+.. _ypid.apt_preferences: https://github.com/ypid/ansible-apt_preferences
+.. _ypid.atd: https://github.com/ypid/ansible-atd
+.. _ypid.auth: https://github.com/ypid/ansible-auth
+.. _ypid.bootstrap: https://github.com/ypid/ansible-bootstrap
+.. _ypid.checkmk_agent: https://github.com/ypid/ansible-checkmk_agent
+.. _ypid.console: https://github.com/ypid/ansible-console
+.. _ypid.copy: https://github.com/ypid/ansible-copy
+.. _ypid.core: https://github.com/ypid/ansible-core
+.. _ypid.cron: https://github.com/ypid/ansible-cron
+.. _ypid.cryptsetup: https://github.com/ypid/ansible-cryptsetup
+.. _ypid.cryptsetup_remote_unlock: https://github.com/ypid/ansible-cryptsetup_remote_unlock
+.. _ypid.debops: https://github.com/ypid/ansible-debops
+.. _ypid.dhclient: https://github.com/ypid/ansible-dhclient
+.. _ypid.dhparam: https://github.com/ypid/ansible-dhparam
+.. _ypid.directories: https://github.com/ypid/ansible-directories
+.. _ypid.disk: https://github.com/ypid/ansible-disk
+.. _ypid.divert: https://github.com/ypid/ansible-divert
+.. _ypid.dnsmasq: https://github.com/ypid/ansible-dnsmasq
+.. _ypid.docker: https://github.com/ypid/ansible-docker
+.. ]]]

docs/includes/80post.rst

@@ -0,0 +1,54 @@
+.. Projects [[[
+
+.. _Debian: https://en.wikipedia.org/wiki/Debian
+.. _GNU: https://en.wikipedia.org/wiki/GNU_Project
+.. _Linux: https://en.wikipedia.org/wiki/Linux
+.. _PfSense: https://en.wikipedia.org/wiki/PfSense
+.. _FreeBSD: https://en.wikipedia.org/wiki/FreeBSD
+.. _Debian Backports: http://backports.debian.org/
+
+.. _yaml2rst: https://github.com/htgoebel/yaml2rst
+.. _LUKS: https://en.wikipedia.org/wiki/Linux_Unified_Key_Setup
+.. _dm-crypt: https://en.wikipedia.org/wiki/Dm-crypt
+.. _cryptsetup: https://gitlab.com/cryptsetup/cryptsetup
+.. _X2go: http://wiki.x2go.org/
+.. _Wine: https://en.wikipedia.org/wiki/Wine_%28software%29
+.. _ownCloud: https://owncloud.org/
+.. _Let's Encrypt: https://letsencrypt.org/
+
+.. _Opsi: https://en.wikipedia.org/wiki/Opsi
+.. _paedML Linux: https://www.lmz-bw.de/technische-unterstuetzung/kundenportal/linux.html
+.. _linuxmuster.net: https://linuxmuster.net/
+.. _Univention Corporate Server: https://en.wikipedia.org/wiki/Univention_Corporate_Server
+
+.. ]]]
+
+.. IT [[[
+
+.. _OCSP: https://en.wikipedia.org/wiki/Online_Certificate_Status_Protocol
+.. _DHCP: https://en.wikipedia.org/wiki/Dynamic_Host_Configuration_Protocol
+.. _OCSP stapling: https://en.wikipedia.org/wiki/OCSP_stapling
+
+.. _PKI: https://en.wikipedia.org/wiki/Public_key_infrastructure
+.. _HSTS: https://en.wikipedia.org/wiki/HTTP_Strict_Transport_Security
+.. _Semantic Versioning: http://semver.org/
+
+.. ]]]
+
+.. DebOps project links [[[
+
+.. _DebOps: http://debops.org/
+.. _DebOps documentation: http://docs.debops.org/en/latest/
+.. _DebOps Contrib: https://github.com/debops-contrib/debops-contrib
+.. _DebOps Contrib playbooks: https://github.com/debops-contrib/debops-contrib-playbooks
+
+.. ]]]
+
+.. DebOps people [[[
+
+.. FIXME: Change to debops-keyring
+
+.. _drybjed: https://wiki.debops.org/wiki:user:drybjed
+.. _ypid: https://wiki.debops.org/wiki:user:ypid
+
+.. ]]]