New gencode schema index page with categorisation

[noursaidi]

Example - https://noursaidi.github.io/udmi/gencode/docs/

This change intends to make the schema browser easier to use now that there are a lot more defined schemas.

Changes:

• Schema is now automatically generated for any page which is a "root" schema (not referenced by another schema file) or deliberately excluded (event.json). This prevents pages being created for state_pointset etc.
• Use MD file rather than HTML file
• Use categorisation. If a schema is given a category in etc/schema_categories.txt then it'll be placed unread that category , otherwise it's lodged into the Other category
• Add description of schema to the page

[grafnu]

I put together noursaidi#14 to try some things out -- if you like them you can/should merge that PR into your branch, and then we'll merge them all into faucetsdn...

[grafnu]

I'd like to avoid the name "category" for this, since it's overloaded then with docs/specs/categories.md -- when I first saw this I was expecting something else. Section? schema_sections.txt or something would be ok I think! Alternatively, how hard would it be to have the section specified in the schema file itself? We could have a special field "$section" and just pull the value from there?

[noursaidi]

Would be easy to do. I did think about this, but wasn't sure if JSON Schema permits additional keywords not defined in the schema? (assuming we want to remain compliant with JSON Schema)? The only existing keyword which could be used was $comment

[grafnu]

Maybe rename to "gencode_schemas"? I'm trying to have at least some logical structure... bin/ is getting crowded, so having some structure there would be helpful, I think!

[noursaidi]

Could add it into a script called gencode_doc_utils along with other gendoc related scripts to reduce the number of those? I don't think gencode_schemas is a good name for this particular script.

Incidentally .. I was planning to split the HTML documentation generation out of gendocs and calling that gencode_schemas because gencode_docs itself is getting messy to work with

[grafnu]

schema_readme.md (just because it maps to readme.md not index.md). Also, maybe add an in there somewhere that explains where this ends up? Just so if somebody is looking at this they have some hint!

[grafnu]

Don't specifically care if it's gencode_schemas or gencode_rockets :-) -- just as long as it's prefaced with gencode_ then all good. The other refactor is fine too... not particular about it as long as there's some kind of structure/hierarchy in place.

…

On Wed, Aug 31, 2022 at 12:15 PM Noureddine ***@***.***> wrote: ***@***.**** commented on this pull request. ------------------------------ In bin/list_root_schemas <#436 (comment)>: > @@ -0,0 +1,92 @@ +#!/usr/bin/env python3 Could add it into a script called gencode_doc_utils along with other gendoc related scripts to reduce the number of those? I don't think gencode_schemas is a good name for this particular script. Incidentally .. I was planning to split the HTML documentation generation out of gendocs and calling *that* gencode_schemas because gencode_docs itself is getting messy to work with — Reply to this email directly, view it on GitHub <#436 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAIEPD7BBANAIRMFBRA3H43V36VNFANCNFSM6AAAAAAQBMAIUA> . You are receiving this because your review was requested.Message ID: ***@***.***>

[grafnu]

NB: Prefer not 1st person language for docs. E.g., "If these tests are failing, check the basic system requirements (Linux with...) -- Just a style thing trying to avoid the tutorial mode of writing. Or like below ("If..., check...") is ok (just avoid you/I/we is all :-).

[grafnu]

pending file name change

[noursaidi]

@grafnu file renamed and documentation updated, PTAL