c8f1173de0
This commit only contains the generator changes for easier review The bulleted list of subprojects makes it impossible to link someone to specific info for a given subproject. Now, instead of linking someone to sig-testing#subprojects and asking them to scroll, I link them directly to sig-testing#kind. While I was at this, I made the main SIG/WG/UG/Committee contact info format match what is used for subprojects, specifically: - display the slack channel name - list github teams as part of contact info instead of in a table - use - instead of * for bullets I also removed subproject rendering from WGs, since WGs cannot own code, and added a link to the governance definition of what a subproject is. |
||
|---|---|---|
| .. | ||
| testdata | ||
| .gitignore | ||
| OWNERS | ||
| README.md | ||
| aliases.tmpl | ||
| app.go | ||
| app_test.go | ||
| committee_readme.tmpl | ||
| header.tmpl | ||
| list.tmpl | ||
| sig_readme.tmpl | ||
| ug_readme.tmpl | ||
| wg_readme.tmpl | ||
README.md
SIG Doc builder
This folder contains scripts to automatically generate documentation about the
different Special Interest Groups (SIGs), Working Groups (WGs),
User Groups (UGs) and Committees of Kubernetes. The authoritative
source for SIG information is the sigs.yaml file in the project root.
All updates must be done there.
The schema for this file should be self explanatory. However, if you need to see all the options, check out the generator code in app.go.
The documentation follows a template and uses the values from sigs.yaml:
- Header:
header.tmpl - List:
list.tmpl - SIG README:
sig_readme.tmpl - WG README:
wg_readme.tmpl - UG README:
ug_readme.tmpl - Committee README:
committee_readme.tmpl
Time Zone gotcha:
Time zones make everything complicated.
And Daylight Saving time makes it even more complicated.
Meetings are specified with a time zone and we generate a link to http://www.thetimezoneconverter.com/ so people can easily convert it to their local time zone.
To make this work you need to specify the time zone in a way that the web site recognizes.
Practically, that means US pacific time must be PT (Pacific Time).
PT isn't good enough, unfortunately.
When an update happens to the this file, the next step is to generate the accompanying documentation. This takes the format of the following types of doc files:
sig-<sig-name>/README.md
wg-<working-group-name>/README.md
ug-<user-group-name>/README.md
committee-<committee-name>/README.md
sig-list.md
For example, if a contributor has updated sig-cluster-lifecycle, the
following files will be generated:
sig-cluster-lifecycle/README.md
sig-list.md
How to use
To (re)build documentation for all the SIGs in a go environment, run:
make generate
or to run this inside a docker container:
make generate-dockerized
To build docs for one SIG, run one of these commands:
make WHAT=sig-apps
make WHAT=cluster-lifecycle
make WHAT=wg-resource-management
make WHAT=container-identity
where the WHAT var refers to the directory being built.
Adding custom content
README
If your SIG, WG, UG or Committee wishes to add custom content, you can do so by placing it within the following code comments:
<!-- BEGIN CUSTOM CONTENT -->
<!-- END CUSTOM CONTENT -->
Anything inside these code comments are saved by the generator and appended to newly generated content. Updating any content outside this block, however, will be overwritten the next time the generator runs.
An example might be:
<!-- BEGIN CUSTOM CONTENT -->
## Upcoming SIG goals
- Do this
- Do that
<!-- END CUSTOM CONTENT -->
OWNERS_ALIASES
Similarly, custom aliases can be added in the OWNERS_ALIASES file by placing
it within the following code comments:
## BEGIN CUSTOM CONTENT
## END CUSTOM CONTENT