Drop 'brodocs' backend for API reference generation #102
Conversation
k8s-ci-robot
added
the
cncf-cla: yes
k8s-ci-robot
added
the
size/XL
|
[APPROVALNOTIFIER] This PR is APPROVED This pull-request has been approved by: tengqm 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 |
k8s-ci-robot
added
the
approved
gen-apidocs/generators/writer.go
Outdated
| panic(fmt.Sprintf("Unknown backend specified: %s", *Backend)) | ||
| } | ||
|
|
||
| writer := NewHTMLWriter(config, copyright, title) |
There was a problem hiding this comment.
nit: indentation of line 61?
There was a problem hiding this comment.
indentation should be one TAB according Go convention. I have got TABs autoconverted to 4 spaces in my VIM. Will fix.
| @@ -84,74 +84,3 @@ func PrintInfo(config *api.Config) { | |||
| // } | |||
| //} | |||
| } | |||
|
|
|||
There was a problem hiding this comment.
Is PrintInfo(), JsonOutputFile(manifest.json) used?
There was a problem hiding this comment.
PrintInfo is still referenced, by JsonOutputFile is not (will fix).
There was a problem hiding this comment.
@tengqm , How do these changes affect the generation of the kubectl command reference?
docker run -v $(shell pwd)/gen-kubectldocs/generators/includes:/source -v $(shell pwd)/gen-kubectldocs/generators/build:/build -v $(shell pwd)/gen-kubectldocs/generators/:/manifest pwittrock/brodocs
Eventually the tooling/build of the kubectl reference will be updated (I hope to reopen the related kubectl reference generation PR and continue work) too.
There was a problem hiding this comment.
This change is irrelevant to the gen-kubectldocs. This PR is only related to the API reference generation. I'd like to have the kubectl reference reworked as well.
We cannot afford maintaining two backends for generating the reference docs. This PR drops the legacy 'brodocs' way of building refernece docs. We drop it because: - The brodocs container has to be managed by a specific person so the team collaboration model is not scalable. - The brodocs container has not been maintained for a long period. - The markdown output from the brodocs container are difficult to tune for web presentation -- main use case of the tool. - The new 'html' generator has been used for several release cycles and it is generating satisfactory output for users. It can be considered mature.
tengqm
force-pushed
the
drop-brodocs-build
branch
from
3e9d914
to
5eedcc9
Compare
|
@tengqm , Looks fine. Do you know what version of the k8s API was the last version to be generated from the |
|
/lgtm |
k8s-ci-robot
added
the
lgtm
We cannot afford maintaining two backends for generating the reference
docs. This PR drops the legacy 'brodocs' way of building refernece docs.
We drop it because:
team collaboration model is not scalable.
for web presentation -- main use case of the tool.
it is generating satisfactory output for users. It can be considered
mature.