New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Use global link definitions. #155

Open
ypid opened this Issue Jul 7, 2016 · 4 comments

Comments

Projects
None yet
1 participant
@ypid
Copy link
Member

ypid commented Jul 7, 2016

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:

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 ypid added the enhancement label Jul 7, 2016

ypid added a commit to ypid/ansible-resources that referenced this issue Jul 7, 2016

@ypid

This comment has been minimized.

Copy link
Member Author

ypid commented Jul 7, 2016

@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 ypid self-assigned this Jul 12, 2016

ypid added a commit to ypid/docs-1 that referenced this issue Jul 12, 2016

Support global link definitions.
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.)

Implements: debops#155

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
```

Copy https://github.com/debops/docs/tree/master/docs/includes/global.rst
to `docs/includes/global.rst`

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 all. Enjoy 😉

ypid added a commit to ypid/docs-1 that referenced this issue Jul 12, 2016

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

ypid added a commit to ypid/test-suite that referenced this issue Jul 15, 2016

ypid added a commit to ypid/ansible-owncloud that referenced this issue Jul 16, 2016

@ypid

This comment has been minimized.

Copy link
Member Author

ypid commented 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.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 added a commit to ypid/debops-playbooks that referenced this issue Jul 17, 2016

Use global.rst hyperlink definition.
Automated edit done by: https://github.com/ypid/ypid-ansible-common/blob/1a1128714b2bedb0ae427b8e4879084542558117/bin/sphinx-inline
Some changes had to be manually reverted to make the build pass (e. g.
  variable not defined in this single docs context).

Related to: debops/docs#155
@ypid

This comment has been minimized.

Copy link
Member Author

ypid commented Jul 17, 2016

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

This comment has been minimized.

Copy link
Member Author

ypid commented Jul 18, 2016

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

@ypid ypid added the approved label Jul 18, 2016

ypid added a commit to ypid/ansible-hashicorp that referenced this issue Jul 23, 2016

Utilize the full power of the DebOps docs format
* Use global.rst hyperlinks. Ref: debops/docs#155
* Use Sphinx inline syntax: Example: debops/docs#153
* Fixed typos

Most of the changes are an automated edit done by [sphinx-inline](https://github.com/ypid/ypid-ansible-common/blob/master/bin/sphinx-inline).

PR depends on: debops/docs#191

ypid added a commit to ypid/ansible-owncloud that referenced this issue Aug 9, 2016

ganto added a commit to ganto/ansible-checkmk_agent that referenced this issue Nov 2, 2016

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment