Re: AGL API Documentation

[Stephane Desneux <stephane.desneux@xxxxxxx>]

Hi all,

TL;DR: IoT.bzh proposed the 'afbidl' description format in November 2018. With
this format, the GPS API looks like this:

https://git.automotivelinux.org/apps/agl-service-gps/tree/api/gps-service-geolocation.yml?h=sandbox/benierc/newapis

Feedback is welcome!

---

Details:

There's an ongoing task to specify an API schema (see SAT meeting minutes back
in November 2018 [1] as well as SPEC-1903 [2])

Back in 2018, some people at IoT.bzh investigated on API specification formats
(openAPI, asyncAPI ... and other IDLs). The conclusion at that time was that
none of the existing formats has the required features: some are too
web-centric, others not fitted for describing unattended events, some others too
complex = not human readable/writable.

So we decided to create a specific schema 'afbidl' that fits with the concept of
AGL bindings and covers all the features we need:
* written in readable YAML or JSON (YAML for human, JSON for machines)
* describe APIs in details: verbs, events, datatypes, unit tests + expected
results ... leveraging JsonSchema spec (https://json-schema.org/)
* having an online editor should be pretty easy (we could imagine something
close to [3])
* generators can read the API description and produce various outputs:
   - code skeleton / stubs
   - API tests for QA
   - API compliance information (test if a binding complies with the API using
introspection)
   - documentation (markdown for doc site, HTML for local usage, text, pdf ...)
   - ...

For the documentation part, the format we propose includes the "book schema"
already used in repositories to describe the available documentation (example
here[4]).

We took the simple GPS API to show what it would look like: see [5] for the API
description and [6] for some generated HTML (formatting is missing).

[1]:https://wiki.automotivelinux.org/agl-sat-meetings#november_22_2018
[2]:https://jira.automotivelinux.org/browse/SPEC-1903
[3]:http://editor.asyncapi.org/
[4]:https://git.automotivelinux.org/apps/agl-service-can-low-level/tree/docs/api-services-book.yml
[5]:https://git.automotivelinux.org/apps/agl-service-gps/tree/api/gps-service-geolocation.yml?h=sandbox/benierc/newapis
[6]:https://iot.bzh/download/public/tmp/gps-service-geolocation.html

---
Stephane Desneux - CTO - IoT.bzh
stephane.desneux@xxxxxxx - www.iot.bzh

On 03/07/2019 03:43, Walt Miner wrote:
> TL;DR We need to standardize the methods we use to describe and document AGL
> APIs. I propose a site model ourselves after and the steps we need to get there.
> The SAT will discuss this on Thursday and in person in two weeks.
> 
> Currently the documentation site has a general landing page for all APIs. [1].
> If you jump to the link of a particular API on the page you get the git
> directory of the API.  From there you may or may not find useful documentation
> and the documentation methodology is not standardized across the project.  
> 
> What we would like to see is something like we see in the Fuchsia project
> documentation site. [2]. Clicking on one of the APIs [3] you can clearly see
> where the documentation came from (a FIDL file) and you get a nice human
> readable description of the API with optional explanations for each API.   In
> looking at the Fuchsia source code, the API documentation that is rendered on
> the web site resides with SDK.  There are some FIDL objects or calls in the
> target source code that matches the FIDL in the SDK.  There looks to be some
> kind of generation step to create the FIDL files. 
> 
> I do not know how we get from where we are today to where we need to be. I would
> put forth that we need a human readable version of our APIs that is similar to
> the Fuchsia project.
> 
> The steps AGL needs to take to this level of documentation includes: 
> 
> a) Agree upon  a way to extract the API information from the existing into an
> AGL documentation file (not FIDL since it is more of an overall IDL and code
> generator). 
> b) Get someone to write the initial version of a tool that does the extraction
> and places the documentation in an agreed upon place for the doc site.  However
> this done we need to ensure there is a tie between the actual source code and
> the documentation. 
> c) Finish the documentation for all APIs listed on the documentation site. 
> 
> The good news is that I think we have lot of the pieces in place to get this
> done quickly and some resources to help us get there.  I will add this topic to
> the SAT call on Thursday and in person in two weeks. 
> 
> Regards,
> Walt
> 
> [1] https://docs.automotivelinux.org/docs/en/master/apis_services/reference/api-reference/0-api-introduction.html
> [2] https://fuchsia.dev/reference/fidl
> [3] https://fuchsia.dev/reference/fidl/fuchsia.media.audio
> 
> -- 
> Walt Miner
> 
>  <https://twitter.com/VStarWalt>
> 
> AGL Community Manager
> The Linux Foundation
> mobile: +1.847.502.7087
> 
> 
> Visit us at:
> automotive.linuxfoundation.org <http://automotive.linuxfoundation.org>
> www.linuxfoundation.org <http://www.linuxfoundation.org>
> 
> 
> 
> _______________________________________________
> automotive-discussions mailing list
> automotive-discussions@xxxxxxxxxxxxxxxxxxxxxxxxx
> https://lists.linuxfoundation.org/mailman/listinfo/automotive-discussions
> 
_______________________________________________
automotive-discussions mailing list
automotive-discussions@xxxxxxxxxxxxxxxxxxxxxxxxx
https://lists.linuxfoundation.org/mailman/listinfo/automotive-discussions