Migrate BareMetalHost and HardwareData API docs from BMO to user-guide

[SafeEHA]

This PR fixes issue #314

[metal3-io-bot]

Hi @SafeEHA. Thanks for your PR.

I'm waiting for a metal3-io member to verify that this patch is reasonable to test. If it is, they should reply with /ok-to-test on its own line. Until that is done, I will not automatically test new commits in this PR, but the usual testing commands by org members will still work. Regular contributors should join the org to skip this step.

Once the patch is verified, the new status will be reflected by the ok-to-test label.

I understand the commands that are listed here.

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository.

[tuminoid]

/ok-to-test

[tuminoid]

/cc @dtantsur

[Rozzii]

IMO this looks good.
/approve

[metal3-io-bot]

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by: Rozzii
Once this PR has been reviewed and has the lgtm label, please assign zaneb for approval. For more information see the Kubernetes Code Review Process.

The full list of commands accepted by this bot can be found here.

Needs approval from an approver in each of these files:

• OWNERS

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

[tuminoid]

We already have status annotation page, this creates second one. We also have BMH states already.

Also none of these pages are linked in the index, so they're not visible to readers.

[Rozzii]

We already have status annotation page, this creates second one. We also have BMH states already.

Also none of these pages are linked in the index, so they're not visible to readers.

Ohh you are right, @SafeEHA as @tuminoid mentioned we have these pages: https://book.metal3.io/bmo/inspect_annotation and https://book.metal3.io/bmo/status_annotation , if there is any extra info in the annotations.md then move it to the inspect and status annotation pages please otherwise you can just delete that from the BMO side.

[SafeEHA]

Thanks, @tuminoid, i noticed the status and inspect annotations already existing in the user-guide have slightly different content in comparison to the ones on BMO, the code block is yaml formatted on the user guide currently and json formatted on BMO, the descriptive content is also slightly different... should I go ahead to take out the new annotations file i created since it already exists?
I'll go ahead to make API visible on the index

[tuminoid]

Thanks, @tuminoid, i noticed the status and inspect annotations already existing in the user-guide have slightly different content in comparison to the ones on BMO, the code block is yaml formatted on the user guide currently and json formatted on BMO, the descriptive content is also slightly different... should I go ahead to take out the new annotations file i created since it already exists? I'll go ahead to make API visible on the index

We should merge the documents so the user guide is as comprehensible as possible.

[SafeEHA]

One final concern, the annotation files on BMO (which is the files referenced in the issue) have different content with the files in user-guide currently, should i focus on merging the files in the user-guide only? its a bit confusing @tuminoid

[tuminoid]

One final concern, the annotation files on BMO (which is the files referenced in the issue) have different content with the files in user-guide currently, should i focus on merging the files in the user-guide only? its a bit confusing @tuminoid

@Rozzii can you assist @SafeEHA which portions to keep and which take?

[dtantsur]

/hold

I don't think the PR is in the right direction.

First, the remaining API docs were not meant to get migrated from BMO.

Second, while inspect and status annotations have some use case overlaps, they also have completely disjoint use cases. If we do decide to merge the pages, we need to add redirects to old pages so that existing links don't lead into nowhere.

Finally, any missing API features we migrate here should be written from a case-based perspective. What am I trying to achieve? How do I do it? What are possible issues?

[dtantsur]

This is covered in the state machine docs (expand if needed)

[dtantsur]

This is already covered in more details in the provisioning docs

[dtantsur]

This deserves a separate page in the advanced features section

[dtantsur]

This also deserves its own advanced page

[metal3-io-bot]

PR needs rebase.

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository.