ironic-python-agent is missing developer documentation

[Jay Faulkner]

IPA currently has no/spotty docstring coverage. On top of this, documents (of any kind) are never generated from the repository.

We should add docstrings to all public functions (and private functions, if we want to overachieve) and make the appropriate infra-config changes to publish documentation.

[OpenStack Infra (hudson-openstack)]

Fix proposed to branch: master
Review: https://review.openstack.org/120662

[OpenStack Infra (hudson-openstack)]

Fix proposed to branch: master
Review: https://review.openstack.org/120663

[OpenStack Infra (hudson-openstack)]

Reviewed: https://review.openstack.org/120660
Committed: https://git.openstack.org/cgit/openstack/ironic-python-agent/commit/?id=69884b669da1c482a85a2726c37100650f7f523f
Submitter: Jenkins
Branch: master

commit 69884b669da1c482a85a2726c37100650f7f523f
Author: Jim Rollenhagen <email address hidden>
Date: Wed Sep 10 15:23:54 2014 -0700

    Add docstrings for agent.py

    Does what it says.

    Partial-Bug: 1367915

    Change-Id: If2617f30c75c4a844c20a60afa41330daf84053a

[OpenStack Infra (hudson-openstack)]

Reviewed: https://review.openstack.org/120661
Committed: https://git.openstack.org/cgit/openstack/ironic-python-agent/commit/?id=a524db83b6337a2b745654b6dd28bb4abd027ac6
Submitter: Jenkins
Branch: master

commit a524db83b6337a2b745654b6dd28bb4abd027ac6
Author: Jim Rollenhagen <email address hidden>
Date: Wed Sep 10 15:24:12 2014 -0700

    Add docstrings for api/ tree

    Does what it says.

    Partial-Bug 1367915

    Change-Id: Id1a718d652f6d98e6acb1d667f42d9c3cc82aef5

[OpenStack Infra (hudson-openstack)]

Reviewed: https://review.openstack.org/120662
Committed: https://git.openstack.org/cgit/openstack/ironic-python-agent/commit/?id=7bf485ea876074a85c4fe5d4fb3858ce98532036
Submitter: Jenkins
Branch: master

commit 7bf485ea876074a85c4fe5d4fb3858ce98532036
Author: Jay Faulkner <email address hidden>
Date: Wed Sep 10 17:42:35 2014 -0700

    Improve docstrings for cmd/agent.py

    Added missing docstrings and improved existing docstrings for every
    method in cmd/agent.py

    Change-Id: Ib8dbbf70bca139a43d75d59fb09dce899466e888
    Partial-bug: 1367915

[OpenStack Infra (hudson-openstack)]

Reviewed: https://review.openstack.org/120663
Committed: https://git.openstack.org/cgit/openstack/ironic-python-agent/commit/?id=8c3595929fe1c8a646cbf6dd5ef08d5d70d44023
Submitter: Jenkins
Branch: master

commit 8c3595929fe1c8a646cbf6dd5ef08d5d70d44023
Author: Jay Faulkner <email address hidden>
Date: Wed Sep 10 17:43:36 2014 -0700

    Improve/add docstrings for CommandResult classes

    Added missing docstrings and improved existing docstrings for every
    method in the CommandResult classes.

    Change-Id: I71ca54a6ee2e3df2705b60bfae7c5a29a2b4657d
    Partial-bug: 1367915

[Dmitry Tantsur (divius)]

Hi Jay, what's the state of this bug? Could you close it if it's fixed?

[OpenStack Infra (hudson-openstack)]

Fix proposed to branch: master
Review: https://review.openstack.org/220293

[Jim Rollenhagen (jim-rollenhagen)]

I'd love to close this... Josh says we're still missing some docstrings.

[OpenStack Infra (hudson-openstack)]

Fix proposed to branch: master
Review: https://review.openstack.org/220313

[OpenStack Infra (hudson-openstack)]

Reviewed: https://review.openstack.org/220293
Committed: https://git.openstack.org/cgit/openstack/ironic-python-agent/commit/?id=b2a86e0b43004ad589fae1e76a026c07b06e7189
Submitter: Jenkins
Branch: master

commit b2a86e0b43004ad589fae1e76a026c07b06e7189
Author: Lindsay K <email address hidden>
Date: Thu Sep 3 12:40:26 2015 -0700

    Fix plural agreement grammar error

    Change-Id: Iab2bc4bee2ef256c43a9c203a4f7495d9716c79a
    Partial-Bug: #1367915

[OpenStack Infra (hudson-openstack)]

Fix proposed to branch: master
Review: https://review.openstack.org/220339

[OpenStack Infra (hudson-openstack)]

Fix proposed to branch: master
Review: https://review.openstack.org/220346

[OpenStack Infra (hudson-openstack)]

Reviewed: https://review.openstack.org/220346
Committed: https://git.openstack.org/cgit/openstack/ironic-python-agent/commit/?id=ac040f5152efae491d6205ad62dc2b7d7b670ced
Submitter: Jenkins
Branch: master

commit ac040f5152efae491d6205ad62dc2b7d7b670ced
Author: Jay Faulkner <email address hidden>
Date: Thu Sep 3 16:15:54 2015 -0700

    Add docstrings for cmd/agent and extensions/clean

    Adding documentation for methods in these files that were missing
    docstrings.

    Change-Id: I2ad9f85605720ab2295dec3d0436ff0af07847c2
    Partial-bug: 1367915

[OpenStack Infra (hudson-openstack)]

Reviewed: https://review.openstack.org/220313
Committed: https://git.openstack.org/cgit/openstack/ironic-python-agent/commit/?id=6131b2e4054dbdff0be7fdeec13b868b1a915783
Submitter: Jenkins
Branch: master

commit 6131b2e4054dbdff0be7fdeec13b868b1a915783
Author: Jay Faulkner <email address hidden>
Date: Thu Sep 3 14:02:28 2015 -0700

    Ensure all methods in utils.py have docstrings

    Previous some of these methods were not well documented. Hopefully they
    now are.

    Change-Id: If73987a2dd234b71a1c2af9b764becc34aee4496
    Partial-bug: 1367915

[OpenStack Infra (hudson-openstack)]

Fix proposed to branch: master
Review: https://review.openstack.org/234519

[OpenStack Infra (hudson-openstack)]

Reviewed: https://review.openstack.org/234519
Committed: https://git.openstack.org/cgit/openstack/ironic-python-agent/commit/?id=f013333949ef74fa0340caa3f68e17e3368ccaa5
Submitter: Jenkins
Branch: master

commit f013333949ef74fa0340caa3f68e17e3368ccaa5
Author: Naohiro Tamura <email address hidden>
Date: Wed Oct 14 11:20:39 2015 +0900

    Add param docstring into the normalize func

    This patch adds a missing param docstring into the normalize function
    in util.py.

    Change-Id: I91ecc0970fc386163657ab521d8cdd898694a426
    Partial-bug: 1367915

[OpenStack Infra (hudson-openstack)]

Fix proposed to branch: master
Review: https://review.openstack.org/288632

[OpenStack Infra (hudson-openstack)]

Change abandoned by Clif Houck (<email address hidden>) on branch: master
Review: https://review.openstack.org/288632

[OpenStack Infra (hudson-openstack)]

Reviewed: https://review.openstack.org/288632
Committed: https://git.openstack.org/cgit/openstack/ironic-python-agent/commit/?id=3cf5369cb6285fe32c310fba7c712c690feb4ea4
Submitter: Jenkins
Branch: master

commit 3cf5369cb6285fe32c310fba7c712c690feb4ea4
Author: Clif Houck <email address hidden>
Date: Fri Mar 4 12:25:46 2016 -0600

    Add docstrings to all functions in Agent standby extension

    Change-Id: Ic8101a6b29dee4b79c2d7f3dc064e4c98a9a0741
    Partial-Bug: 1367915

[Clif Houck (clifhouck)]

This is done? The last change that is tagged with this bug was my addition of documentation to the standby extension. I thought there were a lot more modules that needed docs.

[Jay Faulkner (jason-oldos)]

When this bug was originally filed, there was no dev docs whatsoever for IPA. Now we're to a "normal" level of documentation. There's still improvement to be made, but I don't think it's bad enough to justify a giant catchall bug.

In fact, if we were able to ID the specific pieces that needed docs still, filing specific low-hanging-bug tagged bugs for them would probably help other folks get them done.