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.

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

Test out other resource docs format #4027

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Conversation

IanMadd
Copy link
Contributor

@IanMadd IanMadd commented Jan 19, 2023

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

  • Spell Check
  • Local build
  • Examine the local build
  • All tests pass

@IanMadd IanMadd requested a review from a team as a code owner January 19, 2023 19:15
@netlify
Copy link

netlify bot commented Jan 19, 2023

Deploy Preview for chef-web-docs ready!

Name Link
🔨 Latest commit 4287fc4
🔍 Latest deploy log https://app.netlify.com/sites/chef-web-docs/deploys/63c9980eb06cef0008214b1f
😎 Deploy Preview https://deploy-preview-4027--chef-web-docs.netlify.app
📱 Preview on mobile
Toggle QR Code...

QR Code

Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify site settings.

Signed-off-by: Ian Maddaus <ian.maddaus@progress.com>
@sonarcloud
Copy link

sonarcloud bot commented Jan 19, 2023

Kudos, SonarCloud Quality Gate passed!    Quality Gate passed

Bug A 0 Bugs
Vulnerability A 0 Vulnerabilities
Security Hotspot A 0 Security Hotspots
Code Smell A 0 Code Smells

No Coverage information No Coverage information
0.0% 0.0% Duplication

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

Successfully merging this pull request may close these issues.

1 participant