Add ability to read documentation before installing add-ons

[nvdaes]

Is your feature request related to a problem? Please describe.

Before installing add-ons, it's possible to read info presented activating the About button, not full add-on help. Though add-on URL can be used to get more info about add-ons, webpages are not always updated, specially when add-ons have multiple version, for example for testing.

Describe the solution you'd like

The add-on help button should be available before installing an add-on, similar to About button.

Describe alternatives you've considered

Provide a mechanism to specify documentation for different add-on versions and languages, for example,alist of URLs, though seems tricky and confusing..

Additional context

Many add-ons include documentation, that maybe updated for different versions and can be more consistent that info available on different websites, where people can publish them.

[CyrilleB79]

I answer here to #15579 (comment) since #15579 has been closed as duplicate of this issue.

@seanbudd wrote in #15579 (comment):

The original issue describes the purpose of the homepage button, which already exists.
So the only work remaining here is being able to read a thorough and translated description of the add-on i.e. the add-ons help page.

Keep in mind that these 3 English pages may differ:

• The help page. It's usually the Readme which is also used as first page of GitHub's repo. But some add-on use GitHub's readme as a simple presentation of the add-on and the help target is instead a more detailed user manual html file.
• Home page: It's usually GitHub's repo's main page. But it may be a specific page, unrelated with GitHub's readme or with the help document, e.g. a download page.
• URL of source code: it's usually the GitHub repo's page. But some repos do not show the description / user guide of the add-on. Also, it may be located elsewhere than on GitHub.

[seanbudd]

Shouldn't the help document be translatable - not only English?
NVDA supports this being a translated document. My understand is that this issue intends to implement allowing users to read this document before deciding to install.
I think we can do this by allowing a user to download the add-on file and preview the help document file.
Or just preview the document for an external install.

We could also consider eventually mirroring the help docs on the server, this may be easier once the translation system is migrated.
Some solution like this will have to occur to replace the legacy add-ons website.
i.e. a web front end for the add-on store, with the ability to read translated additional information / help documentation.

[hwf1324]

I think you can refer to the Extensions view of the vs code

[CyrilleB79]

Shouldn't the help document be translatable - not only English?

Of course.
To clarify, #13454 (comment) was only a warning to avoid confusion between these three English pages available in the store:

• the help page, which is a file in the add-on
• the home page
• the source code page

But the help page (at least) is intended to be translated.

My understand is that this issue intends to implement allowing users to read this document before deciding to install.

Correct

I think we can do this by allowing a user to download the add-on file and preview the help document file.

This is a bit problematic for big add-ons:

• The page may be displayed with a delay (download time)
• If the add-on is very big, it may also cause temporary storage issue, e.g. if I look at the help files of all the Store

For big add-on examples, see TesseractOCR (more than 70MB) or XPoseImage Captioner sélectionné (much more than 100MB)

Or just preview the document for an external install.

This part was #14615. But now that the store has changed many things, I need to take some time to update with latest changes.

We could also consider eventually mirroring the help docs on the server, this may be easier once the translation system is migrated. Some solution like this will have to occur to replace the legacy add-ons website. i.e. a web front end for the add-on store, with the ability to read translated additional information / help documentation.

That would be very nice; but of course, it's more work.

[seanbudd]

An alternative for 2024.1 is to allow markdown in the manifest for the long description of an add-on. This field already supports translations so if it supports better formatting, it will be easy to add and browse translated and well formatted information before installing the add-on.

[lukaszgo1]

Mirroring the documentation on the NV Access servers is, indeed, quite a bit of work, and I am not really convinced it is necessary. Assuming we do not need a web front-end to the add-on store my first though would be as follows:

• As part of the transforming add-ons too views content of their (translated!) markdown readme is added to the json file for the add-on
• Then in the store interface NVDA can take advantage of this by converting to HTML, and displaying it in the webview control, therefore no longer forcing user to open the web browser just to read the documentation

Have I missed something? Is there a real need for a web front-end to the store. If so what are use cases for it?

[hwf1324]

A meaningful example is when looking for Add-ons in the Add-on Store that you are interested in, you don't need to download the entire Add-on file and learn what the Add-on is used for.

By the way, why can't Add-on Storr get the documentation data directly from GitHub?