Portal docs appear to be outdated

[swsnr]

I noticed that the flatpak portal documentation differs from the xdg portal documentation, with the latter appearing to be more recent.

Specifically, the flatpak documentation for the Settings portal documents only Read and ReadAll, does not document the confusing return value of Read, and only includes the color-scheme settings.

The xdg portal documentation for the Settings portal documents the newer ReadOne method, deprecates Read due to its confusing return value, and also mentions the accent-color and contrast settings.

As such it appears that the XDG portal documentation is newer, and the flatpak portal docs should be updated.

I can make a pull request but I'm not sure how to proceed. The portal reference documentation in this repo comes from docs/portal-docs.html which doesn't look hand written, but appears to be generated. Unfortunately, there's no reference to the source and how to regenerate it, and the last update commit from three years ago doesn't have any details in its commit message 🤷

And, given that up to date portal documentation exists at https://flatpak.github.io/xdg-desktop-portal/docs/index.html, should the flatpak portal docs perhaps just be removed and replaced with a link to that upstream documentation?

[bbhtt]

These containe some Flatpak specific portal docs that aren't there in XDG portal docs but the rest of it is indeed overlapped.

@TingPing might know the steps to generate them. Building Flatpak just gives a bunch of html files, I don't know how they were combined into one.

[swsnr]

Could the XDG portals be removed from the flatpak docs, so that the flatpak docs only document the flatpak-specific portals, and reference the XDG portal upstream docs for the XDG portals?

Currently, it's quite confusing, and it's easy to see only the older XDG portal docs, as the upstream docs aren't linked anywhere 🤔

[bbhtt]

lf these are autogenerated it will be easier to set up a workflow to keep them in sync and update.

Removing needs to be done manually by someone everytime they update.

[swsnr]

I'm closing this issue. I'm sorry but I no longer care 🤷