Use global link definitions.

[ypid]

TL;DR https://github.com/debops/docs/blob/master/docs/includes/global.rst gets injected into all role docs when the includes directory is present. The global.rst should not be in role repos itself (and ignored using the .gitignore file). To update the global.rst, please add links to the files starting with two digits in https://github.com/debops/docs/tree/master/docs/includes and do make includes/global.rst in https://github.com/debops/docs/tree/master/docs.

This allows to easily refer to Ansible modules, other DebOps roles and so on with a uniform name.

See:

• https://github.com/ypid/ypid-ansible-common/tree/master/template_role/docs/includes
• https://raw.githubusercontent.com/ypid/ypid-ansible-common/master/template_role/docs/getting-started.rst

The script sphinx-debops-role-build can automaticly copy the latest global definitions to roles.

Resources are proposed to be moved to a repo inside the DebOps project. (is ignored in the repo and injected at build time)

[ypid]

@drybjed Heard someone whispering about avoiding redundancy … 😉

Investigate how the global.rst file can be put into a central place in debops/docs. sphinx-debops-role-build can still copy the file as needed into place to allow to build docs for one role.

[ypid]

Just a little detail when using subdirectories in docs/.

To allow local hyperlink definitions, I did go with a two staged include.
E. g. includes/all.rst is used for doc files. includes/all.rst itself includes includes/global.rst, this only works when includes/all.rst was included from docs/.

To still support this. I would suggest a little hack which consists of creating includes/all_from_subdir.rst which includes the global.rst relative to the subdir. When a third dir level is needed, I would suggest includes/all_from_subsubdir.rst (similar to \subsubsection in LaTeX). Example usage check: https://github.com/debops/debops-playbooks/

[ypid]

Hm, readthedocs.org does currently not run the Makefile at all. This means that the global.rst file does not get injected into the submodules at docs build time.

Possible solution:

1. Self hosted docs and locally build them using the Makefile.
2. Execute the nessesary scripts from conf.py, I guess this way, also readthedocs.org would execute shell commands. Otherwise, rewrite linkincludes in Python.

Docs currently work, only without the hyperlinks: http://docs.debops.org/en/latest/debops-playbooks/docs/changelog.html#id123

[ypid]

Now, that’s what I am talking about: http://docs.debops.org/en/latest/debops-playbooks/docs/changelog.html

global.rst file gets injected into each submodule at build time.

Docs build: https://readthedocs.org/projects/debops/builds/4211003/

Fixed by: #178