Simplify docs-check workflow by extracting functionality

[obnoxxx]

Description of your changes:

This simplifies the docs-check workflow by extracting hard-coded functionality into new make targets check-docs and check-helm-docs that can be called locally by the developer to conveniently check if they forgot to commit some generated docs or the multus validation job manifest file

Which issue is resolved by this Pull Request:

Checklist:

• Commit Message Formatting: Commit titles and messages follow guidelines in the developer guide.
• Skip Tests for Docs: If this is only a documentation change, add the label skip-ci on the PR.
• Reviewed the developer guide on Submitting a Pull Request
• Pending release notes updated with breaking and/or notable changes for the next minor release.
• Documentation has been updated, if necessary.
• Unit tests have been added, if necessary.
• Integration tests have been added, if necessary.

[BlaineEXE]

This is intentional. Please revert.

[obnoxxx]

@BlaineEXE wrote:

This is intentional. Please revert.

done. commit removed

[parth-gr]

lgtm

[BlaineEXE]

Rook has a new initiative to make docs more imperative (notably avoiding "we" and "you" in docs), so this is a good time to update this paragraph.

Suggested change

	[helm-docs](https://github.com/norwoodj/helm-docs) is a tool that generates the documentation for a helm chart automatically. If there are changes in the helm chart, you need to run helm-docs manually, and check in the resulting autogenerated md files at the path `/Documentation/Helm-Charts`
	[helm-docs](https://github.com/norwoodj/helm-docs) is a tool that generates the documentation for a helm chart automatically. If there are changes in the helm chart, you need to run helm-docs manually, and check in the resulting autogenerated md files at the path `/Documentation/Helm-Charts`. We have made running helm-docs very easy for you by creating a `make` target for it: you only need to run `make helm-docs`. an additional `make` target exists to help you check if there are uncommitted generated helm chart docs: just run `make check-helm-docs`
	[helm-docs](https://github.com/norwoodj/helm-docs) is a tool that generates the documentation for a helm chart automatically. If there are changes in the helm chart, run `make helm-docs`, and check in the resulting autogenerated markdown files at the path `/Documentation/Helm-Charts`.

After thinking about this, if I imagine myself to be a new contributor, I think I would be confused how running make helm-docs is improved by also running make check-helm-docs. I think it might end up being less confusing new contributors to have this target be something that is not officially documented.

Improvements for new contributors is certainly valuable, and reducing the barrier to entry is worthwhile. In service of that and in a related vein as this PR, something that I think would be most impactful and useful would be to have a make target that runs all auto-generation targets including docs, helm-docs, crds, and any I forgot. The only exception I would make would be make codegen which takes too long to run.

[obnoxxx]

@BlaineEXE - do I get it right that you are requesting to remove the new mention of the new make target from this section altogether? I can also try to make the wording clearer and avoid using "we" and "you" ...

[obnoxxx]

@obnoxxx wrote:

@BlaineEXE - do I get it right that you are requesting to remove the new mention of the new make target from this section altogether?

Alternatively, I can also try to make the wording clearer and avoid using "we" and "you" ...

I have done that and updated the PR

[BlaineEXE]

@BlaineEXE - do I get it right that you are requesting to remove the new mention of the new make target from this section altogether? I can also try to make the wording clearer and avoid using "we" and "you" ...

Yes. When I read this while imagining standing in the shoes of a new contributor, I think I would feel overwhelmed by the length of the text and confused about what make targets to run. Short and sweet is best, and I've especially noticed this to be true for users/contributors who are in Asia and don't have the same mastery of English.

[travisn]

make docs also makes the helm docs. How about if we just document make docs and no need to document a separate make helm-docs? This will keep the commands simpler. If make helm-docs still exists, that's just an implementation detail that we don't need to document.

[obnoxxx]

@travisn wrote:

make docs also makes the helm docs. How about if we just document make docs and no need to document a separate make helm-docs? This will keep the commands simpler. If make helm-docs still exists, that's just an implementation detail that we don't need to document.

done: updated accordingly.

[travisn]

Can we just change this whole section to only talk about running make docs? I still think it's nice to keep the developer docs simple. Did you push the changes from when I asked about this previously? Maybe I'm missing the update.

[obnoxxx]

@travisn wrote:

Can we just change this whole section to only talk about running make docs? I still think it's nice to keep the developer docs simple.

I fully agree!

Did you push the changes from when I asked about this previously? Maybe I'm missing the update.

yes, I did that. here is the updated commit: abcc79e

[travisn]

I'm suggesting to not even mention make helm-docs. Something short like this?

## Making docs

[helm-docs](https://github.com/norwoodj/helm-docs) is a tool that generates the documentation for a helm
chart automatically. If there are changes in the helm chart, the developer needs to run `make docs` 
and check in the resulting autogenerated md files at the path `/Documentation/Helm-Charts`. 

[obnoxxx]

@travisn wrote:

I'm suggesting to not even mention make helm-docs. Something short like this?

## Making docs

[helm-docs](https://github.com/norwoodj/helm-docs) is a tool that generates the documentation for a helm
chart automatically. If there are changes in the helm chart, the developer needs to run `make docs` 
and check in the resulting autogenerated md files at the path `/Documentation/Helm-Charts`. 

I just updated it with very similar wording, not mentioning make helm-docs at all.

[travisn]

Suggested change

	[helm-docs](https://github.com/norwoodj/helm-docs) is a tool that generates the documentation for a helm chart automatically. If there are changes in the helm chart, the developer needs to run `make docs` and check in the resulting autogenerated md files under the path `/Documentation/Helm-Charts`.
	[helm-docs](https://github.com/norwoodj/helm-docs) is a tool that generates the documentation for a helm chart automatically. If there are changes in the helm chart, the developer needs to run `make docs` and check in the resulting autogenerated md files under the path `/Documentation/Helm-Charts`.

[travisn]

Do we need lines 41-43? They seem like details that only someone looking at makefiles needs to know. IMO the developer guide doesn't need these details for normal usage.

[obnoxxx]

@travisn wrote:

Do we need lines 41-43? They seem like details that only someone looking at makefiles needs to know. IMO the developer guide doesn't need these details for normal usage.

I fully agree. removed

[travisn]

Even this line 41 can be removed IMO

[obnoxxx]

@travisn wrote:

Even this line 41 can be removed IMO

I didn't remove it completely, but simplified it, removing the "CI" part ...

[travisn]

Honestly, I don't understand the paragraph. There are some sentence formatting issues and partial sentences.

[obnoxxx]

@travisn wrote:

Honestly, I don't understand the paragraph. There are some sentence formatting issues and partial sentences.

I updated the PR once more to clarify the paragraph. I hope it is clearer now!

Additonally, I am wondering if we should mention that make docs generates more than just helm chart docs

[travisn]

Since make docs also builds the helm docs, do we still need this separate check-helm-docs? Seems like it's already tested by make check-docs?

[obnoxxx]

@travisn wrote:

Since make docs also builds the helm docs, do we still need this separate check-helm-docs? Seems like it's already tested by make check-docs?

good point. I thought about it but decided to keep the separate targets because the check-helm-docs target has a more specific error message, pointing to a helm-docs specific section in the guide.