Add a public API specification

[dwlehman]

Where a class is listed that means instantiating that class is supported. Where is it not, we are specifying the public methods and attributes. There are some issues with undocumented members and singletons, but they are minor.

[vpodzime]

So if for example ~blivet.devices.lvm.LVMLogicalVolumeDevice is listed, it means that all its methods, attributes and properties are part of the API?

[dwlehman]

It means the constructor, any listed methods/attributes, and all methods/attributes listed in superclasses are public.

[dwlehman]

Would it be clearer (if a bit verbose) to explicitly list everything for each class?

[vpodzime]

Well, what if I want one or two methods/attributes not being part of the API?

[dwlehman]

Then you don't list them in the API spec.

[dwlehman]

By "listed" I mean "listed in the API spec".

[vpodzime]

Then you don't list them in the API spec.

Sure, do I need to list all the other methods/attributes then?

[dwlehman]

Yes, and this makes it clear that I should convert it so that every method/attribute is explicitly listed directly in the list for that class instead of expecting users to check the superclass' list.

[dwlehman]

New version has several changes:

• the public API specification is more explicit
• the TOC now only shows top-level items: Introduction, Public API, Testing, &c
• the existing singleton modules were cleaned up a bit:
  • instance and class names don't match
  • class names are public so they get documented
• direct access to full module docs from the streamlined TOC
  • old: blivet->blivet package
  • new: blivet package

@vpodzime please check to see if I missed anything in the new LVM classes.

[dwlehman]

Isn't map_name equal to name for DMDevice (including lvs)?

What about is_thin_lv, is_thin_pool, is_snapshot_lv?

[dwlehman]

Latest version includes the following changes:

• fixed a typo in the singleton cleanup patch
• added more to lvm device API
• drop sphinx mocking entirely (it wasn't working)

[dwlehman]

You can see a preview of the docs here.

[vpodzime]

Isn't map_name equal to name for DMDevice (including lvs)?

It is, right now, but will users of the API know? And is it going to stay like that in the future? I imagine us using e.g. vg_name/lv_name for LV name.

What about is_thin_lv, is_thin_pool, is_snapshot_lv?

Good catch! These too, plus is_internal_lv.

[vpodzime]

Looks good to me otherwise.