Documentation

[Tolriq]

The API extensions and documentation should be auto generated and deployed to github.io pages.

Let's discuss the possible options, as this is not something I'm used to.

If you know a solution and master it please tell :)

What I often see for open source project is https://squidfunk.github.io/mkdocs-material/

[deluan]

I have experience with Google's Docsy. It uses Hugo as the static site generator, and it is full featured. I could setup something with it and a Github Action to auto publish the generated site on every merge.

I rather use Hugo as the static site generator as it is a single binary, so I don't need any language runtime properly installed to be able to render the site locally, but I'm open to other solutions.

Let me know if anyone has any other suggestion.

[Tolriq]

Most tools runs in docker anyway and once the template is finalized will run on github so not a huge differentiator I think.

What matters most is how easy it's to write and update the actual docs, I have no experience with those tools so can't say which one could be better, just that the whole thing is about docs so let's make that as easy as possible to increase the chances that it won't be just one person keeping the docs up to date.

[gravelld]

These look like tools specialised toward technical documentation, bundled with a SSG.

What about the bridge between API and docs? I've used OpenAPI and Swagger before, it might save us some time since we (in theory) only need to write and document the API. I guess extra documentation would still be inevitable.

[deluan]

I started writing an OpenAPI document for the Subsonic API a while ago, with the intention of using it to validate requests and/or generate code with it. Unfortunately the structure of the API is not completely compatible with OpenAPI (ex: XML and JSON responses are really hard to describe), and it makes the OpenAPI doc very hard to follow. So I gave up. We could still maybe use it for documentation only, but I think it is less useful that way. Anyway, I can contribute what I've done once I'm back from vacation, next week.

…

On Thu, 23 Feb 2023 at 09:42, Dan Gravell ***@***.***> wrote: These look like tools specialised toward technical documentation, bundled with a SSG. What about the bridge between API and docs? I've used OpenAPI and Swagger before, it might save us some time since we (in theory) only need to write and document the API. I guess extra documentation would still be inevitable. — Reply to this email directly, view it on GitHub <#2 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AACQ4WKRIPED2KKL5H7R6W3WY5ZMPANCNFSM6AAAAAAVA3NICI> . You are receiving this because you commented.Message ID: ***@***.*** .com>

[gravelld]

Yeah, the breadth of the use cases they try to support in OpenAPI leads to, I think, great complexity and quite a learning curve.

Just putting it out there...

[lachlan-00]

Ampache uses docusaurus for https://ampache.org/api/

which was a breeeeeze compared to other static sites I've used.

All my docs are markdown generated with server examples linked to a build script I run. (Build_python for api responses and build_www for the site)

https://github.com/lachlan-00/ampache-administrator

Which uses my test server to regenerate from the same state.

https://github.com/lachlan-00/ampache-test

Having up to date and valid examples from a source/master server would help a lot of people out and was the hardest thing about updating subsonic when I had no idea what I was doing

[lachlan-00]

hey, i have been putting in 1.16.1 for Ampache (initial commit here ampache/ampache@3484478) and i was looking at making a script to make some calls on the subsonic demo server and saving the responses for comparison to Ampache.

Does anyone think the responses would be valuable to others? I'm going to make the scripts up this week and test it out as i need to probably rewrite Ampache's subsonic responses properly and the examples will help with testing.

[Tolriq]

The response could definitively help to build the documentation for the extensions. There's quite a few places with differences between servers or lack of logic on Subsonic side that would need fixing / documenting.

I was quite busy, but since the vote is over it will be time to move on.

[lachlan-00]

I've added initial default reponses for Subsonic from the demo site and a local install here https://github.com/ampache/python3-ampache/tree/api6/docs/subsonic-6.1.6

Ampache current state is also save in the same repo.
https://github.com/ampache/python3-ampache/tree/api6/docs/ampache-subsonic

[Tolriq]

@opensubsonic/clients @opensubsonic/servers If you have requests or ideas about the documentation part now is the good time to speak :)

With the vote ended to go to extensions first (Does not mean there won't be a V2 is all goes well in the future). It's time to validate the documentation part before going public and gathering more API needs to start building the actual extensions.

[dweymouth]

I can move this to its own discussion if it makes sense, but I'd like to clarify in the documentation the sort order of some of the endpoints:

• getAlbum/getPlaylist - tracks are sorted in the running order (this one should kind of go without saying)
• getArtist - should we choose and document a sort order for the album list? The example Subsonic.org response sorts the artist's albums A-Z, Navidrome returns the list sorted in reverse chronological order (I think this makes the most sense) I suppose each server could do this how they want, but then we need to document that the sort order is undefined so clients know they have to sort it themselves to have a consistent UX across servers
• getStarred(2) - Returns items sorted by date starred descending

[Tolriq]

Yes it will require another discussion, here it's about the tool for the doc.
With that said, does it make sense to add optional sort param to those endpoints?

[gravelld]

I think two use cases are:

• If the collections are long and streaming/chunking is supported, the client can act lazily.
• If you're looking for the "top n" [elements] where the semantics of the sort-by are not implementable given the data that is returned (e.g. it's needed for "most played" but not track running order).

[dweymouth]

Yes, pretty much this. Clients, including mine, that partially/incrementally load paginated collections (e.g. albums list) cannot implement their own sorting. Clients can sort the results of endpoints that a) return the full data at once, and b) return the field to sort on as part of the response

[Tolriq]

So after a lot of work and help from @deluan and the json from @lachlan-00 the doc system is now up and running in the repository.

The site is temporarily published at https://rainbow-profiterole-2b193b.netlify.app/ until the organisation is made public.

Please comment and give your opinion.

[Tolriq]

@opensubsonic/servers @opensubsonic/clients

[jeffvli]

Looks good to me!

[epoupon]

Looks great! Thanks for this amazing work

[deluan]

What is still missing to make the org public?

[Tolriq]

The validation of #5 by all. Then add that to the doc. Then public.