search

Skarlso / crd-to-sample-yaml

Generate a sample YAML file from a CRD and view it rendered on a nice website
https://crdtoyaml.com/
Apache License 2.0
116 stars 17 forks source link

Idea/FeatureRequest: HTML - Add switches for yaml comments / minimum example in Details of each resource #127

Open markussiebert opened 2 weeks ago

markussiebert commented 2 weeks ago

I use cty to generate HTML documentation from a folder of my CRDs, and it works wonderfully!

The existing detailed section for each resource is helpful, but it could be enhanced further by introducing configurable options to provide greater flexibility and clarity.

Feature Request

Enrich the Existing Detail-Section

It would be incredibly useful if cty could extend the current detailed section for each resource to include the following configurable options:

  1. Show/Hide Comments: A switch to allow showing or not showing the comments above each line of the YAML document if present - similar to the already existing crd flag: -m, --comments If set, it will add descriptions as comments to each line where available.

  2. Minimal vs. All Parameters: A switch to allow toggling between showing a minimal example and an example with all parameters - similar to the already existing crd flag: -l, --minimal If set, only the minimal required example yaml is generated.

Benefits

I think this would make this awesome tool even better!

Skarlso commented 2 weeks ago

Hello. :))

Show/Hide Comments: A switch to allow showing or not showing the comments above each line of the YAML document if present - similar to the already existing crd flag: -m, --comments If set, it will add descriptions as comments to each line where available.

I'm not sure I understand this one. The YAML part is displayed in a code displaying thing, there is nothing you can toggle. In the generated output the "comments" are the Descriptions. Those are collapsable right now, so not sure what you would like to do about those?

Minimal vs. All Parameters: A switch to allow toggling between showing a minimal example and an example with all parameters - similar to the already existing crd flag: -l, --minimal If set, only the minimal required example yaml is generated.

Hum, maybe I can do this. I would have to generate the content twice, have two containers, one in one and the other in the otherone and you can then toggle which content you would like to see. 🤔 That's rather ugly, but there is no other way. This is a static site generated so it needs to have ALL of the data it wants to display.

markussiebert commented 2 weeks ago

I am talking of the YAML/example part of each Kind... I hink of something like:

image

Maybe there can be all variants rendered and the toggles make them visible/invisible?

Skarlso commented 2 weeks ago

The problem is that that section is a code display block. 🤔 For that to work, I would have to generate everything and display a code section that has the comment is full... etc. That's 4 times the entire yaml.

That could possible take some time and would result in a considerably larger HTML output.

markussiebert commented 2 weeks ago

Got it - not that good ^^

What about something like this (needs more styling, but somehow works)

I think there is more logic required for filtering out "optional comments". Wont use code anymore, but styling could be done in div also. 

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <title>Toggle YAML Comments</title>
    <style>
        .hidden-comment {
            display: none;
        }
        .language-yaml {
            display: flex;
            gap: .5rem;
            flex-direction: column;
            background-color: #f4f4f4;
            padding: .5rem;
            border-radius: 4px;
            overflow: auto;
        }
    </style>
</head>
<body>
    <div>
        <button id="toggleComments">Show Comments</button>
        <button id="toggleOptional">Show Optional</button>
    </div>
        <div class="language-yaml" id="yamlCode">
<div>user: john</div>
<div class="hidden-comment"># this is a comment</div>
<div>age: 30</div>
<div class="hidden-comment optional"># another comment</div>
<div class="optional">location: "unknown"</div>
<div>aasdasd</div>
        </div>
    <script>
        document.getElementById('toggleComments').addEventListener('click', function () {
                const yamlCodeElement = document.getElementById('yamlCode');
                const comments = yamlCodeElement.querySelectorAll('.hidden-comment');
                const isCommentsHidden = comments[0].style.display === 'none';

                comments.forEach(comment => {
                        comment.style.display = isCommentsHidden ? 'block' : 'none';
                });

                this.textContent = isCommentsHidden ? 'Hide Comments' : 'Show Comments';
        });
        document.getElementById('toggleOptional').addEventListener('click', function () {
                const yamlCodeElement = document.getElementById('yamlCode');
                const comments = yamlCodeElement.querySelectorAll('.optional');
                const isCommentsHidden = comments[0].style.display === 'none';

                comments.forEach(comment => {
                        comment.style.display = isCommentsHidden ? 'block' : 'none';
                });

                this.textContent = isCommentsHidden ? 'Hide Comments' : 'Show Comments';
        });
    </script>
</body>
</html>
Skarlso commented 1 week ago

I'm not following this, sorry. The displayed content is simply a []byte slice and it's basically just put into the code view <p>. Are you suggesting to go line by line and put everything into different divs and p? That would explode the whole website and would mess up the formatting as well. I'm not a web expert, I don't know how to make that look nicer unless we implement a way to format YAML on a website. :D

markussiebert commented 1 week ago

Ok, no problem - will think about it - maybe I finde a more practical solution :-)

Skarlso commented 1 week ago

Thanks! :) Maybe we can somehow format it line by line. :D I don't know. :D I'm pretty sure it's possible. :P