⚠️ Migrate information away from docs/api.md #1820
Conversation
The motivation of this change is to avoid duplicating information between the inline API docs, the user guide and this page. Some useful bits of information have been migrated to the inline docs, which I also proof-read for mistakes. Then most of the content of api.md has been replaced with references to the rendered CR docs and the user guide. Signed-off-by: Dmitry Tantsur <dtantsur@protonmail.com>
metal3-io-bot
added
the
size/XXL
|
I would like you to please mention the apis/metal3.io/v1alpha1/baremetalhost_types.go in the new api.md just to make it more easily discoverable, there are info now in that file that might help someone better understand the BMO's features. |
There was a problem hiding this comment.
Remember someone might come and argue that inline comments are not documentation!
Although godoc can be easily updated with the code changes not sure if kubebuilder has any best practices for documenting the API some might want docs without going through the code I won't expect the user-guide to have a detailed docs for an API even we cannot force it be up to date with the API changes like being in the same repo
Aren't the already provided links to the rendered CRD docs better? Especially given that
|
We can discuss that if we assume the user has bmo running before checking the API docs |
I'm not sure what you're talking about. Could you please double-check the changes to docs/api.md here? I'm adding links to https://doc.crds.dev/github.com/metal3-io/baremetal-operator/, is it something you don't consider acceptable? In any case, having the same information in 2 places is a recipe for getting outdated information. |
That a good idea I was thinking CRDs docs rendered with kubectl |
|
@Rozzii @mboukhalfa could you re-review given what we've discussed? I believe your requests are already addressed in a slightly better way. |
I will check a bit later in details and might give some feedback I think I do not have the right to lgtm on this repo, I was wondering where the examples like HostFirmwareSettings Example got migrated to ? |
|
I meant mentioning the Like the software and hardware raid are mutually exclusive or that the hostFirmwareSetting CR is an alternative to the BMH firmware field. Just tiny bits of info that might help someone connect the dots better. My request is just to simply put a line in the api.md that say something like this "Additional API implementation details can be found in apis/metal3.io/v1alpha1/baremetalhost_types.go " , just to let the newcomers know that we hove some info bits there too. |
This is a case for a user guide IMO.
Will do |
Signed-off-by: Dmitry Tantsur <dtantsur@protonmail.com>
|
[APPROVALNOTIFIER] This PR is APPROVED This pull-request has been approved by: kashifest, mboukhalfa The full list of commands accepted by this bot can be found here. The pull request process is described here
Needs approval from an approver in each of these files:
Approvers can indicate their approval by writing |
metal3-io-bot
added
the
approved
| // If unspecified or set be 0, the maximum capacity of disk will be used for logical disk. | ||
| // +kubebuilder:validation:Minimum=0 | ||
| SizeGibibytes *int `json:"sizeGibibytes,omitempty"` | ||
|
|
||
| // RAID level for the logical disk. The following levels are supported: 0;1;1+0. | ||
| // RAID level for the logical disk. The following levels are supported: | ||
| // 0, 1 and 1+0. |
There was a problem hiding this comment.
You expect too much of my English grammar :)
| BMC BMCDetails `json:"bmc,omitempty"` | ||
|
|
||
| // RAID configuration for bare metal server | ||
| // RAID configuration for bare metal server. If set, the RAID settings | ||
| // will be applied before the host is provisioned. If not, the current |
There was a problem hiding this comment.
to be more precise, before the host is "ready", right?
There was a problem hiding this comment.
"ready" is not a status, so it can be confusing
The motivation of this change is to avoid duplicating information
between the inline API docs, the user guide and this page.
Some useful bits of information have been migrated to the inline docs,
which I also proof-read for mistakes. Then most of the content of api.md
has been replaced with references to the rendered CR docs and the user
guide.
Signed-off-by: Dmitry Tantsur dtantsur@protonmail.com