search

segler-alex / radiobrowser-api-rust

radio-browser API implementation in rust
GNU Affero General Public License v3.0
231 stars 99 forks source link

improve api docs #42

Closed segler-alex closed 1 year ago

segler-alex commented 4 years ago

some ideas:

An7ar35 commented 3 years ago

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

mdbook

slatedocs

slatedocs

An7ar35 commented 3 years ago

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 commented 3 years ago

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 commented 3 years ago

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

segler-alex commented 3 years ago

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

An7ar35 commented 2 years ago

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.

image

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:

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 commented 2 years ago

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. 👍🏼