Project Resource Documentation Feature

Question about the project resource documentation,


I notice that it's stored as just a flattened text string in the resource.json and not its own resource file.

Often I find in larger projects we are writing files in parallel to our code or views, and adding them to the files list in the resource.json.

Is there any technical reason why the "Documentation" feature couldnt just create a markdown file instead and add it to the files list like how perspective does thumbnail.png's?

Second question, is it possible to attach to every context menu in the project browser with a custom module to do this myself? I know @PGriffith's markdown resource repository has an example of creating a custom resource, but what about extending the builtin resources in the same way as this "Documentation" feature?

Or, maybe this makes more sense as an Ideas post and a feature request?

I appreciate any ideas.

We have some internal plans to improve the ability to document things - not just a markdown-ey resource file, but perhaps some ability to render those markdown files out into a static webpage to semi-automatically generate an entire reference manual for your project.

I don't think you can do things at the level required from a third party module; it would have to be a first-party integration to hook in to these context menus everywhere. If I remember right, the Documentation tool works the way it currently does as a stopgap; adding a to every resource might require adjusting the logic for how each workspace saves & loads resources, which made it a bit of a harder sell at that time.


I appreciate this level of insight!

This sounds like a good built-in project view that can comb the resource structure, and add convenience functionality to create and auto-update those resource.json files. With a text are and markdown viewer this could be a relatively straightforward setup.

Currently we just do everything manually in vscode, but I'd like to try to bring it into the designer in some way.

I just am not a huge fan of making it a requirement to use a view/window to configure your app *cough sepasoft cough *. Using the designer tools would be desired, but I completely understand the reasoning here! Maybe this sounds like an 8.3 feature since it potentially affects workspace save logic, which I have to assume changes in some way with a jump like that.

It might be an 8.3 feature, in case it ends up dependent on the currently-theoretical restructuring to avoid the "resource.json gets automatically updated" thing, but I couldn't confidently say either way for sure.

1 Like

Just to hammer this home, you can't imagine the gifts and blessings that power users and integrators alike will send to the IA headquarters to celebrate this momentous step forward!

1 Like