Bug 1018710

Summary: [RFE] Enhance API documentation
Product: [Retired] oVirt Reporter: Fabian Deutsch <fdeutsch>
Component: ovirt-nodeAssignee: Ryan Barry <rbarry>
Status: CLOSED CURRENTRELEASE QA Contact: bugs <bugs>
Severity: medium Docs Contact:
Priority: medium    
Version: 3.3CC: acathrow, cshao, fdeutsch, gouyang, hadong, huiwa, iheim, jboggs, leiwang, mgoldboi, ovirt-bugs, ovirt-maint, sbonazzo, yaniwang, ycui, yeylon
Target Milestone: ---Keywords: FutureFeature
Target Release: 3.6.0   
Hardware: Unspecified   
OS: Unspecified   
Whiteboard: node
Fixed In Version: Doc Type: Enhancement
Doc Text:
Feature: Enhance API documentation Reason: Result (if any):
 Story Points: ---
Clone Of: Environment:
Last Closed: 2014-08-06 18:20:25 UTC Type: Bug
Regression: --- Mount Type: ---
Documentation: --- CRM:
Verified Versions: Category: ---
oVirt Team: Node RHEL 7.3 requirements from Atomic Host:
Cloudforms Team: --- Target Upstream Version:

Description Fabian Deutsch 2013-10-14 09:04:10 UTC 
Description of problem:
Currently it might not always be obvious how configuration changes can be achieved using Node's API.
Documentation enhacements can improve the situation.
Comment 1 Fabian Deutsch 2013-10-14 09:41:57 UTC 
Hey Yaniwang,

could you explain a bit more in depth where you would like to see what documentation?
Comment 2 Yaning Wang 2013-10-17 01:51:07 UTC 
Hey Fabian

Document like the following will helpful for tester

Two top category

one is corresponding to the TUI
another is corresponding to the functions that can't be used through TUI or some other advanced/hidden feature

For the first category

- Status Inerface
  ...

- Network Interface
  ...

- Logging Interface
  
  class Logging()
     
      get_logrotate_max_log_size()
      get_rsyslog_address()

For the second category

provide the API like

- reload TUI with dev/test mode
- reset log output level
- ...
Comment 3 Itamar Heim 2014-06-29 09:03:30 UTC 
is this meant as a stable public api? would it survive next-gen efforts?
Comment 4 Fabian Deutsch 2014-07-15 18:17:20 UTC 
That is a good question.
To not maintain our own API I'd say we use the logic from anaconda to do the basic system configuration.
Probably work upstream on anaconda/pykickstart to support currently unsupported topics like snmp and netconsole through the ks directives.

But we could also go the other way, and use the API (which this bug is about) and wrap the anaconda parts.

In general it is also the question if Node itself should offer an public API. And if so, on what level it should be, a "Node level" (very high, like puppet) or like on the library level.

At least I am moving out this bug.
Comment 5 Fabian Deutsch 2014-08-06 18:20:25 UTC 
More documentation has been added in the mean time, and even more will be added, closing this bug.