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

Automatically generate template render context documentation #4824

Closed
christophermaier opened this issue Mar 28, 2018 · 1 comment
Closed

Automatically generate template render context documentation #4824

christophermaier opened this issue Mar 28, 2018 · 1 comment
Assignees
@cnunciato
Labels
Documentation Flags an issue / PR for attention by the technical documentation team Focus:Habitat

Comments

@christophermaier
Copy link
Contributor

#4823 introduced a JSON Schema definition of our rendering context. It would be great if we could replace the hand-maintained documentation at https://www.habitat.sh/docs/reference/#template-data with documentation extracted from the schema itself.

Bonus points for adding examples to the schema.
christophermaier added a commit that referenced this issue Mar 29, 2018
@christophermaier
Add leader key to render context bind information
1536148 
Previously, determining the leader of a service group was
complicated. If the service was running in a leader topology, the
`{{bind.<BIND>.first}}` key would be the leader, but we didn't
directly indicate if that was the case (you could have queried to see
if `{{bind.<BIND>.first.leader}}` was `true`, but that leads to some
needlessly verbose templates.

Now, we introduce an explicit `leader` key, which will be non-null if
the service group has a leader. Furthermore, the use of `first` is
deprecated, since the meaning of it is not deterministic (it could be
a non-alive member of the service group, for instance, which is not
what anyone wants). The `first` key will remain in rendering contexts
for the foreseeable future, but users are encouraged to use
`{{bind.<BIND>.leader}}` if they want the leader, and
`{{bind.<BIND>.members[0]}}` otherwise, pending future refactorings.

Documentation is updated to reflect this, and a new `$deprecated` and
`$since` key are used in our JSON Schema to indicate when an old field
is deprecated, and when a new one is introduced. Our JSON Schema
parser is configured to allow non-standard keywords like this through
its processing, and this provides some additional hooks that a future
automated documentation generator can use (see #4824)

Fixes #4127

Signed-off-by: Christopher Maier <[email protected]>
@christophermaier christophermaier mentioned this issue Mar 29, 2018
Merged
@cnunciato cnunciato self-assigned this Apr 2, 2018
@cnunciato
Copy link
Contributor

I'll bet we could generate the hints for the VS Code extension as part of this, too -- I'll take a look at that as well.

christophermaier added a commit that referenced this issue Apr 9, 2018
@christophermaier
Add leader key to render context bind information
16f6009 
Previously, determining the leader of a service group was
complicated. If the service was running in a leader topology, the
`{{bind.<BIND>.first}}` key would be the leader, but we didn't
directly indicate if that was the case (you could have queried to see
if `{{bind.<BIND>.first.leader}}` was `true`, but that leads to some
needlessly verbose templates.

Now, we introduce an explicit `leader` key, which will be non-null if
the service group has a leader. Furthermore, the use of `first` is
deprecated, since the meaning of it is not deterministic (it could be
a non-alive member of the service group, for instance, which is not
what anyone wants). The `first` key will remain in rendering contexts
for the foreseeable future, but users are encouraged to use
`{{bind.<BIND>.leader}}` if they want the leader, and
`{{bind.<BIND>.members[0]}}` otherwise, pending future refactorings.

Documentation is updated to reflect this, and a new `$deprecated` and
`$since` key are used in our JSON Schema to indicate when an old field
is deprecated, and when a new one is introduced. Our JSON Schema
parser is configured to allow non-standard keywords like this through
its processing, and this provides some additional hooks that a future
automated documentation generator can use (see #4824)

Fixes #4127

Signed-off-by: Christopher Maier <[email protected]>
christophermaier added a commit that referenced this issue Apr 12, 2018
@christophermaier
Add leader key to render context bind information
f2e4467 
Previously, determining the leader of a service group was
complicated. If the service was running in a leader topology, the
`{{bind.<BIND>.first}}` key would be the leader, but we didn't
directly indicate if that was the case (you could have queried to see
if `{{bind.<BIND>.first.leader}}` was `true`, but that leads to some
needlessly verbose templates.

Now, we introduce an explicit `leader` key, which will be non-null if
the service group has a leader. Furthermore, the use of `first` is
deprecated, since the meaning of it is not deterministic (it could be
a non-alive member of the service group, for instance, which is not
what anyone wants). The `first` key will remain in rendering contexts
for the foreseeable future, but users are encouraged to use
`{{bind.<BIND>.leader}}` if they want the leader, and
`{{bind.<BIND>.members[0]}}` otherwise, pending future refactorings.

Documentation is updated to reflect this, and a new `$deprecated` and
`$since` key are used in our JSON Schema to indicate when an old field
is deprecated, and when a new one is introduced. Our JSON Schema
parser is configured to allow non-standard keywords like this through
its processing, and this provides some additional hooks that a future
automated documentation generator can use (see #4824)

Fixes #4127

Signed-off-by: Christopher Maier <[email protected]>
@christophermaier christophermaier added Documentation Flags an issue / PR for attention by the technical documentation team and removed A-documentation labels Aug 18, 2020
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees

@cnunciato cnunciato

Labels
Documentation Flags an issue / PR for attention by the technical documentation team Focus:Habitat
Projects
None yet
Milestone
No milestone
Development

No branches or pull requests
2 participants
@christophermaier @cnunciato