[RFC] Add info/docs page for each plugin

[PartyWumpus]

This is now waiting for some plugin API changes so the docs folder can easily be included (or not included).

Resolves #428

Adds an info button to the top of each plugin. When pressed it'll load one or more markdown files.

Current folder layout is this

~/homebrew/plugins/[pluginname]
├── docs
│   ├── docs.json
│   ├── en-US
│   │   ├── file1.md
│   │   └── file2.md
│   └── fr-FR
│       ├── file1.md
│       └── file2.md
├── main.py
...
└── README.md

or this if you don't want translations

├── docs
│   ├── docs.json
│   ├── file1.md
│   └── file2.md
├── main.py
...
└── README.md

docs.json: (These are the default values if the file is missing or incomplete)

{
    "default_language": "en-US",
    "include_readme": "False",
    "file_list": ["filename1.md","filename2.md"],   // if this isn't set then the loader will just guess
    "use_translation": "True"   // if this isn't set then the loader will just guess
}

If the docs.json file is missing/broken, it'll just display every file in the folder.
If a language's folder is missing, it'll just use the default_language's folder.
If a page is present in the default_language's folder, but not in the user's language, then it'll display the default language's page.
If the docs folder is missing, it'll just display the readme file.

in each file there's a bit of (optional) frontmatter that determines the name used in the sidebar
if it isn't there then the default is the filename without the extension

---
title: This is the title
---
# the actual markdown goes here
*the frontmatter doesn't show up in the file*

In each file, you can link to images/videos in the /assets folder of your plugin with /decky/assets/filename.

changes that I still need to make are:

• Wait for the DFL change that adds the ScrollPanel stuff and use that instead feat: add components found while working on tabmaster decky-frontend-lib#90
• Add way to easily put images in the docs
• Add a setting somewhere to allow devs to completely disable the info button for their plugin.
• Add some way of putting separators in between pages in the sidebar.
• Add extra config options like not showing the title.
• Try to make links properly selectable within the scrollable element
• Some system to allow internal links

As the [RFC] implies, please share any feedback.

Pictures:

[JohnnyCrazy]

Related to #428

[JohnnyCrazy]

What do you think about moving the idea of docs.json into the frontmatter of each file? So

{
    "file1.md": "Title of this page1",
    "file2.md": "Title of this page2"
}

becomes

// file1.md
---
title: Title of this page1
---

// file2.md
---
title: Title of this page2
---

Less config files sounds like a good thing.

[PartyWumpus]

What do you think about moving the idea of docs.json into the frontmatter of each file?

This sounds like a very good idea, I considered something similar but wasn't sure exactly how to implement it. Would also probably make the logic of the loading of files a little simpler.

[NGnius]

From the technical side, I can see a couple of downsides to that:

• Every file must be read to build the list of titles for the frontend's side menu (bad scalability)
• Frontmatter is valid markdown (risk of parsing/display bugs)

Both are solvable problems, just things to keep in mind. The advantages seem to outweigh those challenges.

Since it's only the title, is there any reason to not just always use <title>.md? I.e. use the filename as the title and just remove the file extension. Filenames can have spaces and most special characters in Linux so it's not too hard to write titles with good punctuation (unlike Windows).

[PartyWumpus]

Since it's only the title, is there any reason to not just always use <title>.md?

I want files to be able to fall back to the original language's version of that file if they don't exist in your language. If they're named that way there's no clear way to fall back for individual files. If it isn't considered particularly important, then that could be fine. (it could obviously still fall back to the original language's folder if your language doesn't exist at all)

Also, I just remembered the reason why I didn't do it the frontmatter way, because it gives no clear order and I'd like devs to be able to order their pages, and if possible add seperators between pages in the list. I think a consistent order is probably reasonably important.
I suppose I could still use frontmatter for the title and move the ordering done by docs.json into the singular config file as an (optional) list.

[ReanimationXP]

Just thought I'd throw in that "perfect is the enemy of good" here. This ultimately is a basic feature and personally I'd settle for a single file readme.md for each plugin. Honestly that should suffice (and should be required, imo), rather than a multipage multifile tabulated novel. Translations are understandable but beyond that, it's a plugin of a plugin. If you need to write a book about it, just link to your github. /shrug

As for 'add a setting somewhere for whether to show the button or not', no file present = no button displayed, solved. Also, I'd like to see whatever this description is on the store page as well as after the plugin is installed, so whatever that looks like that'd be awesome.

My 2 cents you didn't ask for ;)

[TrainDoctor]

Wanting to know if there will be any more work on this RFC? The feature is a great idea but I worry that adapting it into the current codebase and getting plugin authors to utilize it would be difficult.

[PartyWumpus]

I think this PR was over scoped, it would've been nice if I'd finished it but I think it does too much. An easy way to include arbitrary files (like markdown files) is probably the better way of making the doc writing experience better. The new plugin API might already do this even?

[TrainDoctor]

I think this PR was over scoped, it would've been nice if I'd finished it but I think it does too much. An easy way to include arbitrary files (like markdown files) is probably the better way of making the doc writing experience better. The new plugin API might already do this even?

I do not believe we have arbitrary file support yet but I think most plugins have what they need at the moment. Closing for now with the understanding that this doesn't fit with how most of plugin devs see plugins working going forward.