improve api docs

[segler-alex]

some ideas:

• add sidemenu that is always visible with the document structure
• split up into more files, not one big file
• use bigger part of the screen (e.g.: left=sidemenu, center=text, right=examples)
• use some framework to make edit easier (https://crates.io/crates/mdbook, https://orchid.run/wiki/user-manual/getting-started/directory-structure, https://slatedocs.github.io/slate ...)

[An7ar35]

Hey there, since I'm using your API for ctune I figured I'd have a go at contributing a little bit as a small token of thanks.

I've played around with both mdbook and state and there are different compromises. mdbook is easier to deal with but having a 3rd pane with code inside is not something that comes out of the box. slate does but on first look is limited to whatever list of code languages is set at the beginning meaning that some will be empty at times.

Anyway, here are a couple of rough screenshots to give you an idea. Let me know your thoughts.

mdbook

slatedocs

[An7ar35]

I've copied/adapted everything over to slatedocs in a branch for preview.

Environment variables are API_SERVER and API_VERSION for setting the server and version respectively during build (see docker_run.sh).

There is still the matter of: 1/ Icon on the top left to change 2/ Deciding how to setup and deploy all that - My thoughts are to create a separate documentation repo with a fork of slatedocs as advised in their wiki, add the api source markdown to it and then just use it as a git sub module and execute slatedocs on that with the /static/ directory as the build directory target if that makes sense. 3/ optionally add missing examples for the csv and m3u/pls tabs for completeness' sake (that can be done later).

Need feedback on the direction you'd like to take this to before I can proceed any further.

Thanks!

[segler-alex]

Thank you a lot for your help!!! the output of slate looks really cool, and it lets the user find stuff much easier. i always wanted to add some better examples (curl, wget,... something like that) to the docs, this seems noch much easier and better to look at. i am in the process of migrating from github to gitlab, i think it would help with automatic building which i also feel is better in gitlab. (i have a lot of gitlab experience from my work :) the automatic build i will find a solution for, if you just do the rest of migrating the docs, maybe add examples i cannot thank you enough.

[segler-alex]

do you think there would be license problems with bundling the output of slate with radiobrowser-api-rust?

[segler-alex]

Is the output of slate self contained? does it load stuff from the internet?

[An7ar35]

Thank you a lot for your help!!!

You're more than welcome. This is a cool project you made! :)

do you think there would be license problems with bundling the output of slate with radiobrowser-api-rust?

IANAL, but looking at this, it looks like using Apache 2 in GPL should be ok as long as there is the license and copyright notice_ as well as any state changes made (which in our case is a little in the config.rb file only).

Also, the generated site (/build/*) is self-contained and does not look to fetch anything remote (I checked on the dev > network panel in FF and Opera and got no remote activity when loading index.html). The generated 'self-contained' site does include slatedocs generated JS code, CSS and some fonts though.

i always wanted to add some better examples (curl, wget,... something like that) to the docs, ...

There is a small-ish caveat to slatedocs in that regard: in order to differentiate code into the code tabs on the right, the code snippets need to be categorised with one of the documented supported languages for rouge. Meaning that not all (json/xml/csv/m3u/pls/curl/wget) might be able to get their own tab since they do not all have direct support in rouge.

Currently I am using for the tabs:

• JSON json
• XML: xml
• CSV: shell
• m3u/pls: plaintext

In order to accommodate curl, wget, and shell based command csv would need to go somewhere else and shell-based example would need to be grouped together too. On the other hand, http could be used to display generic HTTP GET request method examples though.?

Let me know what categories (tab) you'd like based on that and I'll edit/add as required.

[phranck]

I've copied/adapted everything over to slatedocs in a branch for preview.

Slate is great. I used it to build the API documentation for Arylic's DIY audio boards. The original and very outdated documentation came from Linkplay (the producer of white label hardware which Arylic uses) as a very ugly PDF. So I transferred everything to Slate initially. Now I work very close with Arylic and the documentation becomes more and more useful for developers (and even more up to date). The built in search function is a real plus!

So, I would say Slate is very good choice for documenting an API. 👍🏼