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

markussiebert · 2024-10-17T16:32:17Z

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:

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.
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

Enhanced clarity for end-users who are trying to understand and implement the resources.
Improved documentation quality — making it easier to find and interpret resource information.
Maximum flexibility for end-users to customize their view based on their needs.

I think this would make this awesome tool even better!

The text was updated successfully, but these errors were encountered:

Skarlso · 2024-10-17T20:09:57Z

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 · 2024-10-18T06:30:03Z

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

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

Skarlso · 2024-10-18T07:12:52Z

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.

no comments
- full
- not full
with comments
- full
- not full

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

markussiebert · 2024-10-18T17:33:47Z

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 · 2024-10-19T08:08:36Z

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 · 2024-10-19T10:19:05Z

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

Skarlso · 2024-10-19T16:01:47Z

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

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

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

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

markussiebert commented Oct 17, 2024 •

edited

Loading

Skarlso commented Oct 17, 2024

markussiebert commented Oct 18, 2024

Skarlso commented Oct 18, 2024

markussiebert commented Oct 18, 2024 •

edited

Loading

Skarlso commented Oct 19, 2024

markussiebert commented Oct 19, 2024

Skarlso commented Oct 19, 2024

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

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

Comments

markussiebert commented Oct 17, 2024 • edited Loading

Feature Request

Enrich the Existing Detail-Section

Benefits

Skarlso commented Oct 17, 2024

markussiebert commented Oct 18, 2024

Skarlso commented Oct 18, 2024

markussiebert commented Oct 18, 2024 • edited Loading

Skarlso commented Oct 19, 2024

markussiebert commented Oct 19, 2024

Skarlso commented Oct 19, 2024

markussiebert commented Oct 17, 2024 •

edited

Loading

markussiebert commented Oct 18, 2024 •

edited

Loading