Skip to content
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.

Sign up for GitHub

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

Jump to bottom

Use global link definitions. #155

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

Use global link definitions. #155

ypid opened this issue Jul 7, 2016 · 4 comments
Assignees
@ypid
Labels
approved enhancement

Comments

@ypid
Copy link
Member

ypid commented Jul 7, 2016 •
edited
Loading

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 added a commit to ypid/ansible-resources that referenced this issue Jul 7, 2016
@ypid
Added custom delayed paths and updated to latest role standards.
07c0fc2 
Covers:

* debops/docs#155
* debops/docs#154
* debops/yaml2rst#3 (comment)
@ypid
Copy link
Member Author

ypid commented Jul 7, 2016 •
edited
Loading

@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 mentioned this issue Jul 7, 2016
Closed
@ypid ypid self-assigned this Jul 12, 2016
ypid added a commit to ypid/docs-1 that referenced this issue Jul 12, 2016
@ypid
Support global link definitions.
54b56a3 
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
@ypid
Support global link definitions.
833bd7d 
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 ypid mentioned this issue Jul 12, 2016
Merged
ypid added a commit to ypid/test-suite that referenced this issue Jul 15, 2016
@ypid
Fix test when global.rst include file in docs is used.
69f9876 
Related to: debops/docs#155
ypid added a commit to ypid/ansible-owncloud that referenced this issue Jul 16, 2016
@ypid
Removed includes/global.rst as it gets injected at docs build time.
202b309 
Related to: debops/docs#155
@ypid
Copy link
Member Author

ypid commented Jul 17, 2016 •
edited
Loading

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
@ypid
Use global.rst hyperlink definition.
25700af 
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
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
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
@ypid
Utilize the full power of the DebOps docs format
a356088 
* 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 ypid mentioned this issue Jul 23, 2016
Merged
ypid added a commit to ypid/ansible-owncloud that referenced this issue Aug 9, 2016
@ypid
Removed includes/global.rst as it gets injected at docs build time.
a822828 
Related to: debops/docs#155
ganto added a commit to ganto/ansible-checkmk_agent that referenced this issue Nov 2, 2016
@ganto
Update documentation according to latest guidelines
91aa1c1 
Also see:
- debops/docs#139
- debops/docs#155
@ypid ypid mentioned this issue Nov 22, 2016
Merged
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees

@ypid ypid

Labels
approved enhancement
Projects
None yet
Milestone
No milestone
Development

No branches or pull requests
1 participant
@ypid