Test out other resource docs format #4027
Open
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
✅ Deploy Preview for chef-web-docs ready!
To edit notification comments on pull requests, go to your Netlify site settings. |
Signed-off-by: Ian Maddaus <ian.maddaus@progress.com>
IanMadd
force-pushed
the
im/resource_test_update
branch
from
8cab572
to
4287fc4
Compare
|
Kudos, SonarCloud Quality Gate passed!
|
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Signed-off-by: Ian Maddaus ian.maddaus@progress.com
Description
This is an attempt to test out a different way of organizing resource docs content (data and markdown files).
This is what I've figured out so far and I think it works pretty well. I think the question to address is will it make it easier to update resource docs for the next version of Infra Client.
I'm trying this out on the apt_package and alternatives resource pages. It's a bit crude still, but this is what they look like:
Resource content is organized like this:
content/resources/RESOURCE/
| - data.yaml
| - examples.md
| - index.md
| - resource_description.md
| - syntax_description.md
data.yaml
This file primarily contains data about resource properties and actions. It could include other data that's easily sourced from the chef/chef resource files. Maybe the version of Client that a resource was added in.
Note that I'm using this to generate the syntax sample.
examples.md
Pretty self explanatory. Optional.
index.md
Contains page metadata, menu data, and resource page data like additional sections of text that might be added to a page, for example, the Multiple Packages section in the apt_package page.
resource_description.md
Pretty self explanatory.
syntax_description.md
Optional file
Anything that can't be defined automatically by reading through a list of properties and generating a code sample. For example, see the first few lines of text in the Syntax section of the apt_package resource.
Definition of Done
At this point I'm just testing things.
Issues Resolved
https://chefio.atlassian.net/browse/INFC-401
https://chefio.atlassian.net/browse/DOC-212
Related PRs
Check List