Repository navigation
Use global link definitions. #155
Description
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)
Activity
Added custom delayed paths and updated to latest role standards.
ypid commentedon Jul 7, 2016
@drybjed Heard someone whispering about avoiding redundancy … 😉
Investigate how the
global.rstfile 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.Support global link definitions.
Support global link definitions.
Fix test when global.rst include file in docs is used.
Removed includes/global.rst as it gets injected at docs build time.
ypid commentedon Jul 17, 2016
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.rstis used for doc files.includes/all.rstitself includesincludes/global.rst, this only works whenincludes/all.rstwas included fromdocs/.To still support this. I would suggest a little hack which consists of creating
includes/all_from_subdir.rstwhich includes theglobal.rstrelative to the subdir. When a third dir level is needed, I would suggestincludes/all_from_subsubdir.rst(similar to\subsubsectionin LaTeX). Example usage check: https://github.com/debops/debops-playbooks/Use global.rst hyperlink definition.
ypid commentedon Jul 17, 2016
Hm, readthedocs.org does currently not run the Makefile at all. This means that the
global.rstfile does not get injected into the submodules at docs build time.Possible solution:
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 commentedon Jul 18, 2016
Now, that’s what I am talking about: http://docs.debops.org/en/latest/debops-playbooks/docs/changelog.html
global.rstfile gets injected into each submodule at build time.Docs build: https://readthedocs.org/projects/debops/builds/4211003/
Fixed by: #178
Utilize the full power of the DebOps docs format
Removed includes/global.rst as it gets injected at docs build time.
Update documentation according to latest guidelines