On the state of documentation

[Patrick Williams]

The sdbusplus generator that is used on the *-dbus-interfaces repos already supports generating markdown documentation for the APIs. This was suppose to be roughly equivalent to the “old” documentation. 

The plan was:
  1. Enhance the make files to run the markdown generator. 
  2. Add a Jenkins job that would run it and publish to the openbmc.github.io repo on merge to an *-dbus-interfaces repo. 

I don’t think either of these steps has been done but they are also not a significant effort. 

Have you looked at the current markdown generation output to see if this would be helpful?

Patrick
Sent from my iPhone

> On Nov 15, 2017, at 12:11 AM, Stewart Smith <stewart at linux.vnet.ibm.com> wrote:
> 
> Hi all,
> 
> thought I'd try and contribute my thoughts here, as a consumer of
> OpenBMC rather than a developer on it.
> 
> The message has long been that the REST API is what should be used to
> interact with the BMC, and as such we now have a lot of tooling that
> does just that (and we're not the only ones).
> 
> Over the past $months, it's been frustrating (to say the least) that
> there hasn't been any good documentation of this API.
> 
> Indeed, If I look at the API on the "Rusty's API Scale" of usability:
> http://ozlabs.org/~rusty/index.cgi/tech/2008-03-30.html
> http://ozlabs.org/~rusty/index.cgi/tech/2008-04-01.html
> It's all pretty high on the negatives, although it does vary on what
> specific API you're looking at.
> 
> A lot of the negative scoring here is due to a near complete absence of
> documentation. Most things that we use have ended up being documented
> either in the implementation (which may or may not allow you to use it
> correctly), or by some random thread on an IBM internal slack channel.
> 
> Additionally, this issue and PR has come up:
> "Remove org.openbmc.* from REST server"
> https://github.com/openbmc/openbmc/issues/2378
> https://gerrit.openbmc-project.xyz/#/c/7422/
> 
> This morning, I took a stab at going through the documentation and
> working out what this means for current documentation:
> https://gerrit.openbmc-project.xyz/#/c/7916/
> 
> In short: it's not good. There is now no longer documentation even
> describing how to turn the host on and off.
> 
> If the above "remove org.openbmc.* from REST server" is merged, there
> will be *ZERO* documentation on how to turn the host on and off - which
> is about the most simple thing you want to do with a BMC.
> 
> Is there a plan to attack this?
> 
> IMNSHO I'd like to see a standard interface be "the way" to talk to
> OpenBMC based systems, something like RedFish, which I noticed there was
> the start of some work on here: https://gerrit.openbmc-project.xyz/#/c/7786/
> 
> But even if RedFish/IPMI became *the* way externally, the internal APIs
> (as in, d-bus APIs) could probably also do with some love.
> 
> My initial stab at helping with that is:
> https://gerrit.openbmc-project.xyz/#/c/7923/
> but even then, that very same API raises a lot of other questions that I
> haven't addressed - and even in that pull request, I've made a bunch of
> sweeping statements binding the OpenBMC developers to certain API
> stability constraints.
> -- 
> Stewart Smith
> OPAL Architect, IBM.
>