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/
+
+.. ]]]