diff --git a/docs/book/book.toml b/docs/book/book.toml new file mode 100644 index 000000000..10e6c6fb5 --- /dev/null +++ b/docs/book/book.toml @@ -0,0 +1,24 @@ +[book] +authors = ["The Cluster API Provider GCP Maintainers"] +language = "en" +multilingual = false +src = "src" +title = "Kubernetes Cluster API Provider GCP" + +[output.html] +curly-quotes = true +git-repository-url = "https://sigs.k8s.io/cluster-api-provider-gcp" +no-section-label = true + +[output.html.redirect] +"/agenda.html" = "/agenda/2024.html" +"/agenda/2024.html" = "https://docs.google.com/document/d/1l8B947Je79ZJX7zmKnJyMcOMIWjNidvp5FMTnPAY72I/" + +[preprocessor.tabulate] +command = "mdbook-tabulate" + +[preprocessor.embed] +command = "mdbook-embed" + +[preprocessor.releaselink] +command = "mdbook-releaselink" diff --git a/docs/book/src/SUMMARY.md b/docs/book/src/SUMMARY.md new file mode 100644 index 000000000..a200874cc --- /dev/null +++ b/docs/book/src/SUMMARY.md @@ -0,0 +1,21 @@ +# Summary + +[Introduction](./introduction.md) +- [Getting Started](./getting-started.md) +- [Topics](./topics/index.md) + - [Prerequisites](./topics/prerequisites.md) + - [Conformance](./topics/conformance.md) + - [GKE Support](./topics/gke/index.md) + - [Creating a Cluster](./topics/gke/creating-a-cluster.md) + - [Cluster Upgrades](./topics/gke/cluster-upgrades.md) + - [Enabling](./topics/gke/enabling.md) + - [Disabling](./topics/gke/disabling.md) + - [Machine Locations](./topics/machine-locations.md) + - [Preemptible VMs](./topics/preemptible-vms.md) + - [Flannel](./topics/flannel.md) +- [Developer Guide](./developers/index.md) + - [Development](./developers/development.md) + - [Creating a cluster](./developers/cluster-creation.md) + - [CI Jobs](./developers/jobs.md) + - [Releasing](./developers/releasing.md) +- [Roadmap](./roadmap.md) diff --git a/docs/book/src/developers/index.md b/docs/book/src/developers/index.md new file mode 100644 index 000000000..369aa88cd --- /dev/null +++ b/docs/book/src/developers/index.md @@ -0,0 +1,3 @@ +Everything you need to know about contributing to CAPG. + +If you are new to the project and want to help but don't know where to start, you can refer to the [Cluster API contributing guide](https://github.com/kubernetes-sigs/cluster-api/blob/main/CONTRIBUTING.md). diff --git a/docs/book/src/getting-started.md b/docs/book/src/getting-started.md new file mode 100644 index 000000000..01a83b6d9 --- /dev/null +++ b/docs/book/src/getting-started.md @@ -0,0 +1 @@ +{{#embed-github repo:"kubernetes-sigs/cluster-api" path:"docs/book/src/user/quick-start.md"}} diff --git a/docs/book/src/introduction.md b/docs/book/src/introduction.md new file mode 100644 index 000000000..3bad00702 --- /dev/null +++ b/docs/book/src/introduction.md @@ -0,0 +1 @@ +{{#include ../../../README.md}} diff --git a/docs/book/src/topics/index.md b/docs/book/src/topics/index.md new file mode 100644 index 000000000..85fe60813 --- /dev/null +++ b/docs/book/src/topics/index.md @@ -0,0 +1 @@ +This section contains information about the main CAPG features and how to use them. diff --git a/docs/book/theme/css/general.css b/docs/book/theme/css/general.css new file mode 100644 index 000000000..cdd6d7c06 --- /dev/null +++ b/docs/book/theme/css/general.css @@ -0,0 +1,588 @@ +/* Base styles and content styles */ + +@import 'variables.css'; + +html { + font-family: "Lato", "Open Sans", sans-serif; + color: var(--fg); + background-color: var(--bg); + text-size-adjust: none; +} + +body { + margin: 0; + font-size: 1rem; + overflow-x: hidden; +} + +code { + font-family: "IBM Plex Mono", "Source Code Pro", Consolas, "Ubuntu Mono", Menlo, "DejaVu Sans Mono", monospace, monospace; + font-size: 0.875em; /* please adjust the ace font size accordingly in editor.js */ +} + +.left { float: left; } +.right { float: right; } +.hidden { display: none; } +.play-button.hidden { display: none; } + +h2, h3 { margin-top: 2.5em; } +h4, h5 { margin-top: 2em; } + +.header + .header h3, +.header + .header h4, +.header + .header h5 { + margin-top: 1em; +} + +a.header:target h1:before, +a.header:target h2:before, +a.header:target h3:before, +a.header:target h4:before { + display: inline-block; + content: "»"; + margin-left: -30px; + width: 30px; +} + +.page { + outline: 0; + padding: 0 var(--page-padding); +} +.page-wrapper { + box-sizing: border-box; +} +.js .page-wrapper { + transition: margin-left 0.3s ease, transform 0.3s ease; /* Animation: slide away */ +} + +.content { + overflow-y: auto; + padding: 0 15px; + padding-bottom: 50px; +} +.content main { + margin-left: auto; + margin-right: auto; + max-width: var(--content-max-width); +} +.content a { text-decoration: none; } +.content a:hover { text-decoration: underline; } +.content img { max-width: 100%; } +.content .header:link, +.content .header:visited { + color: var(--fg); +} +.content .header:link, +.content .header:visited:hover { + text-decoration: none; +} + +table { + width: 100%; + border-collapse: collapse; +} +table td { + padding: 3px 20px; + border: 1px var(--table-border-color) solid; +} +table thead { + background: var(--table-header-bg); +} +table thead td { + font-weight: 700; + border: none; +} +table thead tr { + border: 1px var(--table-header-bg) solid; +} +/* Alternate background colors for rows */ +table tbody tr:nth-child(2n) { + background: var(--table-alternate-bg); +} + + +blockquote { + margin: 20px 0; + padding: 0 20px; + color: var(--fg); + background-color: var(--quote-bg); + border-top: .1em solid var(--quote-border); + border-bottom: .1em solid var(--quote-border); +} + + +:not(.footnote-definition) + .footnote-definition, +.footnote-definition + :not(.footnote-definition) { + margin-top: 2em; +} +.footnote-definition { + font-size: 0.9em; + margin: 0.5em 0; +} +.footnote-definition p { + display: inline; +} + +.tooltiptext { + position: absolute; + visibility: hidden; + color: #fff; + background-color: #333; + transform: translateX(-50%); /* Center by moving tooltip 50% of its width left */ + left: -8px; /* Half of the width of the icon */ + top: -35px; + font-size: 0.8em; + text-align: center; + border-radius: 6px; + padding: 5px 8px; + margin: 5px; + z-index: 1000; +} +.tooltipped .tooltiptext { + visibility: visible; +} + +/* From here on out is custom stuff */ + +/* marker docs styles */ + +/* NB(directxman12): The general gist of this is that we use semantic markup + * for the actual HTML as much as possible, and then use CSS to look pretty and + * extract the actual relevant information. Theoretically, this'll let us do + * stuff like transform the information for different screen widths. */ + +/* the marker */ +.marker { + display: flex; + flex-wrap: wrap; + align-items: center; + margin-bottom: 0.25em; +} + +/* the marker name */ +.marker > dt.name::before { + content: '// +'; +} +.marker > dt.name { + font-weight: bold; + order: 0; /* hack around the ::before's positioning to get it after the line */ +} + +/* the target blob */ +.marker::before { + content: "on " attr(data-target); + padding: 1px 6px; + border-radius: 20%; + background: var(--quote-bg); + margin-left: 0.5em; + font-weight: normal; + opacity: 0.75; + font-size: 0.75em; + order: 2; /* hack around the ::before's positioning to get it after the line */ +} + +/* deprecated markers */ +.marker.deprecated[data-target] { + /* use attribute marker for specificity */ + order: 4; + opacity: 0.65; +} + +.marker.deprecated::before { + content: "deprecated (on " attr(data-target) ")"; + color: red; +} +.marker.deprecated:not([data-deprecated=""])::before { + content: "use " attr(data-deprecated) " (on " attr(data-target) ")"; + color: red; +} + +/* the summary arguments (hidden in non-summary view) */ +.marker dd.args { + margin-left: 0; + font-family: mono; + order: 1; /* hack around the ::before's positioning to get it after the line */ +} +.marker dl.args.summary { + display: inline-block; + margin-bottom: 0; + margin-top: 0; +} +/* TODO(directxman12): optional */ +.marker dl.args.summary dt { + display: inline-block; + font-style: inherit; +} +.marker dl.args.summary dt:first-child::before { + content: ':'; +} +.marker dl.args.summary dt::before { + content: ','; +} +/* hide in non-summary view */ +.marker dd.args { + display: none +} + +/* the description */ +.marker dd.description { + order: 3; /* hack around the ::before's positioning to get it after the line */ + width: 100%; + display: flex; + flex-direction: column; +} + +/* all arguments */ +.marker dl.args dt.argument::after { + content: '='; +} +.marker dl.args dd.type { + font-style: italic; +} +.marker .argument { + display: inline-block; + margin-left: 0; +} +.marker .argument.type { + font-size: 0.875em; +} +.marker .literal { + font-family:"IBM Plex Mono", "Source Code Pro", Consolas, "Ubuntu Mono", Menlo, "DejaVu Sans Mono", monospace, monospace; + font-size: 0.875em; /* please adjust the ace font size accordingly in editor.js */ +} +.marker .argument.type::before { + content: '‹'; +} +.marker .argument.type::after { + content: '›'; +} + +/* summary args */ +.marker .args.summary .argument.optional { + opacity: 0.75; +} + +/* anonymous marker args */ +.marker.anonymous .description details { + order: 1; + flex: 1; /* don't cause arg syntax to wrap */ +} +.marker.anonymous .description .args { + order: 0; /* go before the description */ + + /* all on a single line */ + margin-top: 0; + margin-bottom: 0; + margin-right: 1em; +} +.marker.anonymous .description { + flex-direction: row; +} +.marker .description dl.args:empty { + margin-top: 0; +} + +.marker .type .slice::before { + content: '[]'; +} + +/* description args */ +.marker .description dt.argument.optional::before { + content: "opt"; + padding: 1px 4px; + border-radius: 20%; + background: var(--quote-bg); + opacity: 0.5; + margin-left: -3em; + float: left; +} + +/* help text */ +.marker summary.no-details { + list-style: none; +} +.marker summary.no-details::-webkit-details-marker { + display: none; +} + +/* summary view */ +.markers-summarize:checked ~ dl > .marker dd.args { + display: inline-block +} +.markers-summarize:checked ~ dl > .marker dd.description dl.args { + display: none +} +.markers-summarize:checked ~ dl > .marker dd.description { + margin-bottom: 0.25em; +} + +input.markers-summarize { + display: none; +} +label.markers-summarize::before { + margin-right: 0.5em; + content: '\25bc'; + display: inline-block; +} +input.markers-summarize:checked ~ label.markers-summarize::before { + content: '\25b6'; +} + +/* misc */ +/* marker details should be indented to be in line with the summary, + * which is indented due to the expando + */ +.marker details > p { + margin-left: 1em; +} + +/* sort by target */ +.marker[data-target="package"] { + order: 2; +} +.marker[data-target="type"] { + order: 1; +} +.marker[data-target="field"] { + order: 0; +} +.markers { + display: flex; + flex-direction: column; +} + +/* details elements (not markers) */ +details.collapse-code { + margin-top: 0.125em; + margin-bottom: 0.125em; +} + +details.collapse-code > summary { + width: 100%; + cursor: pointer; + display: flex; + box-sizing: border-box; /* why isn't this the default? :-/ */ +} + +details.collapse-code > summary::after { + content: "\25c0"; + float: right; + font-size: 0.875em; + color: var(--inline-code-color); + opacity: 0.8; +} + +details.collapse-code[open] > summary::after { + content: "\25bc"; +} + +details.collapse-code > summary pre { + flex: 1; + box-sizing: border-box; /* why isn't this the default? :-/ */ + margin: inherit; + padding: 0.25em 0.5em; +} + +details.collapse-code > summary pre span::after { + content: " (hidden)"; + font-size: 80%; +} + +details.collapse-code[open] > summary pre span::after { + content: ""; +} + +details.collapse-code > summary pre span::before { + content: "// "; +} + +/* make summary into code a bit nicer looking */ +details.collapse-code[open] > summary + pre { + margin-top: 0; +} + +/* get rid of the ugly blue box that makes the summary->code look bad */ +details.collapse-code summary:focus { + outline: none; + font-weight: bold; /* keep something around for tab users */ +} + +/* don't show the default expando */ +details.collapse-code > summary { + list-style: none; +} +details.collapse-code > summary::-webkit-details-marker { + display: none; +} + + +/* diagrams */ + +.diagrams { + display: flex; + flex-direction: row; + align-items: center; +} + +.diagrams > * { + margin-left: 1em; + margin-right: 1em; + font-size: 160%; + font-weight: bold; +} + +.diagrams object, .diagrams svg { + max-width: 100%; + max-height: 10em; /* force svg height to behave */ +} + +.diagrams path, .diagrams polyline, .diagrams circle { + stroke: var(--fg); +} + +.diagrams path.text { + fill: var(--fg); + stroke: none; +} + +.diagrams path.text.invert { + fill: black; + stroke: none; +} + +/* notes */ +aside.note { + border: 1px solid var(--searchbar-border-color); + border-radius: 3px; + margin-top: 1em; +} + +aside.note > * { + margin-left: 1em; + margin-right: 1em; +} + +/* note title */ +aside.note > h1 { + border-bottom: 1px solid var(--searchbar-border-color); + margin: 0; + padding: 0.5em 1em; + font-size: 100%; + font-weight: normal; + background: var(--quote-bg); +} + +/* warning notes */ +aside.note.warning > h1 { + background: var(--warning-note-background-color, #fcf8f2); +} +aside.note.warning > h1::before { + /* TODO(directxman12): fill in these colors in theme. + * If you're good with colors, feel free to play around with this + * in dark mode. */ + content: "!"; + color: var(--warning-note-color, #f0ad4e); + margin-right: 1em; + font-size: 100%; + vertical-align: middle; + font-weight: bold; + padding-left: 0.6em; + padding-right: 0.6em; + border-radius: 50%; + border: 2px solid var(--warning-note-color, #f0ad4e); +} + +/* literate source citations */ +cite.literate-source { + font-size: 75%; + font-family: "IBM Plex Mono","Source Code Pro", Consolas, "Ubuntu Mono", Menlo, "DejaVu Sans Mono", monospace, monospace; +} +cite.literate-source::before { + content: "$ "; + font-weight: bold; + font-style: normal; +} + +cite.literate-source > a::before { + content: "vim "; + font-style: normal; + color: var(--fg); +} + +/* hide the annoying "copy to clipboard" buttons */ +.literate pre > .buttons { + display: none; +} + +/* add a bit of extra padding for readability */ +.literate pre code { + padding-top: 0.75em; + padding-bottom: 0.75em; +} + +.tabset > input[type="radio"] { + position: absolute; + left: -200vw; +} + +.tabset .tab-panel { + display: none; +} + +.tabset > input:first-child:checked ~ .tab-panels > .tab-panel:first-child, +.tabset > input:nth-child(3):checked ~ .tab-panels > .tab-panel:nth-child(2), +.tabset > input:nth-child(5):checked ~ .tab-panels > .tab-panel:nth-child(3), +.tabset > input:nth-child(7):checked ~ .tab-panels > .tab-panel:nth-child(4), +.tabset > input:nth-child(9):checked ~ .tab-panels > .tab-panel:nth-child(5), +.tabset > input:nth-child(11):checked ~ .tab-panels > .tab-panel:nth-child(6), +.tabset > input:nth-child(13):checked ~ .tab-panels > .tab-panel:nth-child(7), +.tabset > input:nth-child(15):checked ~ .tab-panels > .tab-panel:nth-child(8){ + display: block; +} + +.tabset > label { + position: relative; + display: inline-block; + padding: .6em 1em 1em; + border: 1px solid transparent; + border-bottom: 0; + cursor: pointer; + font-size: 16px; + border-top-right-radius: 4px; + border-top-left-radius: 4px; +} + +.tabset > label::after { + content: ""; + position: absolute; + left: 15px; + bottom: 10px; + width: 20px; + height: 4px; + background: #8d8d8d; +} + +.tabset > label:hover, +.tabset > input:focus + label { + color: #06c; +} + +.tabset > label:hover::after, +.tabset > input:focus + label::after, +.tabset > input:checked + label::after { + background: #06c; +} + +.tabset > input:checked + label { + border-color: #ccc; + border-bottom: 1px solid #fff; + margin-bottom: -1px; +} + +.tab-panel { + padding: 1em 1.4em; + border: 1px solid #ccc; + border-bottom-right-radius: 4px; + border-bottom-left-radius: 4px; + position: relative; +} diff --git a/docs/book/theme/favicon.png b/docs/book/theme/favicon.png new file mode 100644 index 000000000..9f0139ba8 Binary files /dev/null and b/docs/book/theme/favicon.png differ diff --git a/docs/book/theme/head.hbs b/docs/book/theme/head.hbs new file mode 100644 index 000000000..fb574577d --- /dev/null +++ b/docs/book/theme/head.hbs @@ -0,0 +1,7 @@ + + + + +