almenscorner
[FEATURE] Generated documentation Settings Catalog in readable format
Is your feature request related to a problem? Please describe. The generated documentation for Settings Catalog policies is hard to read. It now shows an odata setting type in non human readable format.
Describe the solution you'd like I would like to extract the meaningful name of the setting and it's value together with a description of the setting and show them in a Configuration table in the markdown documentation.
Describe alternatives you've considered I've looked at how another project (IntuneManagement) handles this, and I'am currently working on a pull request for this.
Additional context Improving the readability of Intune policy Settings is like going down the rabbit hole, but for Settings Catalog policies this is doable. I'am currently quite far with a working solution and will share the pull request once I'am satisfied :)
Example of generated documentation before changes:
Example of generated documentation after changes:
I've got this working now for Settings Catalog, ~~but need to fix the documentation formatting of the other objects/policies.~~ Besides from a minor formatting bug, the generated documentation for the other objects/policies looks good! I'll prepare a pull request for you to review @almenscorner
Added pull request for this with the changes https://github.com/almenscorner/IntuneCD/pull/245
Just fixed 1 last bug that occured during updating Intune from backuped JSONs. I added a non-graph custom property to settingdefinitions during backup for displaying the root category in documentation which caused updating a policy in intune to fail. I've fixed this in BaseUpdateModule
Hi,
I have not had the time to review this as it is a very substantial change that is also changing some core functionality. I will try and find time over the coming weeks but it might take some time.
@almenscorner, let me know if I can help you in any way in making the review easier. We can for example schedule a call to go through it together. I've also send you a DM via Slack if you want to get in touch :)
Greetings, Lennard
Thank you!
It's been a time issue for me, recently started a new position and have been focused on getting in to it. I will test this in my env asap and provide feedback.
@almenscorner thanks for your feedback!
Based on your comments, I'm currently trying a different approach that uses an --enrich flag to enable the feature and that retrieves the additional information with just 2 api calls and stores it in 2 separate jsons (so that the backup and restore proces is not influenced by it). This reduces the additional runtime from 222 to about 20 seconds.
The reason I choose for HTML tables over MD ones is because the Description content can be quite long, which reduces the readability of the documentation. What renderers do you expect to have issues rendering it correctly? So I can test them for issues.
Regarding your screenshot with pre install script containing html data itself, could you maybe share a generalized version of the corresponding json so I can test and fix it? You can reach me via Slack (check your DMs).
Thanks!
I don't have any renderers in mind currently that would not render HTML data but rather just a note that there might be some out there where it will not work. Might be a very slim chance however.
The JSON for the app it self has the b64 string of the script, what I think is happening is that it triggers on the fact that the script contains comments and shebangs with # and it thinks it should then be part of the TOC.
@almenscorner I've added a new pull request with my alternative approach which focusses on improving the settings catalog documentation, while minimizing major changes to the code base. I've refrained from using HTML tables, and have also not fixed the base64 decode bug in this one.
Regarding the tests, they run succesfully with this version (I've updated a single test function that I've changed), but did not yet create new tests for my new document_settings_catalog function. I will add tests for that after your review (and after implementing your proposed changes)