Document feature state includes #6000

heidecke · 2017-10-22T09:44:18Z

Move tabs example to generic includes doc
Update toc check blacklist
Add includes doc to contributing sidebar

This change is

k8sio-netlify-preview-bot · 2017-10-22T09:46:08Z

Deploy preview ready!

Built with commit 7933af1

https://deploy-preview-6000--kubernetes-io-master-staging.netlify.com

heidecke · 2017-10-22T09:50:03Z

@chenopis I kept your tabs doc content and moved to to a generic includes statement doc page. Let me know if I should add a page moved for the previous location (docs/tabs-example.md). This was not indexed or displayed on the site, so don't believe it necessary.

jesscodez

Generally looks good, a couple of minor suggestions.

jesscodez · 2017-10-23T16:08:19Z

docs/home/contribute/includes.md

@@ -82,7 +136,7 @@ kubectl apply -f "https://git.io/weave-kube"
 {{ "{% include tabs.md " }}%}
 ````

-### Capturing tab content
+#### Capturing tab content


For clarity, could you add a quick sentence to the end of the previous section ("Main tab code") explaining the following sections? e.g.

The following sections break down into detail how this code works.

jesscodez · 2017-10-23T16:13:30Z

docs/home/contribute/includes.md

@@ -1,12 +1,66 @@
 ---
 approvers:
 - chenopis
-title: Tabs Example
+title: Standard Include Statements


Who is our audience? If we can assume that they are familiar with Jekyll (or that we only want people with that background reading this), this is fine. Otherwise, it might be a bit unclear what this section pertains to (and a new contributor skimming the sidebar might miss it).

I suggest something along the lines of Leveraging custom UI elements with includes statements or a shorter version of that. Let me know if you disagree.

Changed the title to "Custom Jekyll Include Snippets." Let me know if that works!

jesscodez · 2017-10-23T16:14:29Z

docs/home/contribute/includes.md

 ---

+{% capture overview %}
+This page explains the special include statements that can be used in
+Kubernetes documentation markdown.


could you mention that "includes" is a built-in Jekyll function and link out to https://jekyllrb.com/docs/templates/#includes (for the sake of potential new contributors)?

jesscodez · 2017-10-23T16:20:33Z

docs/home/contribute/includes.md

 In a markdown page (.md file) on this site, you can add a tab set to display multiple flavors of a given solution. 

-## Demo
+### Tabs demo


I'd suggest putting a single sentence at the beginning of this demo (and the feature state demo) providing context. e.g.

Below is a demo of the tabs feature. Here it is used to display each of the installation commands for the various Kubernetes network solutions.

heidecke · 2017-10-24T06:02:08Z

@abiogenesis-now updated with your suggestions. Let me know if I made anything worse. :D

steveperry-53 · 2017-10-25T21:56:28Z

docs/home/contribute/includes.md

+
+Read more about includes in the [Jekkyl documentation] (https://jekyllrb.com/docs/includes/).
+{% endcapture %}
+


This link is not rendering correctly. Maybe remove the space between [ ] and ( ).

steveperry-53 · 2017-10-25T21:57:04Z

docs/home/contribute/includes.md

+
+{% capture whatsnext %}
+* Learn about [Jekyll] (https://jekyllrb.com/docs).
+* Learn about [writing a new topic](/docs/home/contribute/write-new-topic/).


Link is not rendering correctly. Remove space between [ ] and ( ).

steveperry-53 · 2017-10-25T21:57:35Z

skip_toc_check.txt

@@ -35,6 +35,7 @@ docs/contribute/page-templates.md
 docs/contribute/review-issues.md
 docs/contribute/stage-documentation-changes.md
 docs/contribute/style-guide.md
+docs/contribute/includes.md
 docs/contribute/write-new-topic.md


Why would we skip the TOC check for includes.md? Or any of these contribution topics, for that matter?

I don't know, I was just following convention from the other pages in this section. @chenopis might have a better idea there??

steveperry-53 · 2017-10-25T21:59:24Z

docs/home/contribute/includes.md

@@ -82,7 +140,9 @@ kubectl apply -f "https://git.io/weave-kube"
 {{ "{% include tabs.md " }}%}
 ````

-### Capturing tab content
+The following sections will break down each of the individual features used.
+


Our style guide recommends present tense.

will break down -> break down

heidecke · 2017-10-26T18:00:27Z

@steveperry-53 Integrated your requested changes. I took the test skip changes out of this PR and will open a new one with updates to those files.

jesscodez · 2017-10-26T18:02:43Z

LGTM after merge conflicts are fixed!

heidecke · 2017-10-26T18:48:34Z

Rebase and merge will fail because tabs-example was removed ( @steveperry-53 ?? ) in #6051. Let me see what I can do to clean up, any suggestions?

- Remove extra kubernetes home in toc

jesscodez · 2017-10-26T19:17:14Z

docs/home/contribute/includes.md

+This page explains the custom Jekyll include snippets that can be used in
+Kubernetes documentation markdown.
+
+Read more about includes in the [Jekkyl documentation](https://jekyllrb.com/docs/includes/).


typo: change to Jekyll?

heidecke · 2017-10-26T19:23:34Z

@abiogenesis-now Fixed the typo.

k8s-ci-robot added cncf-cla: yes Indicates the PR's author has signed the CNCF CLA. size/M Denotes a PR that changes 30-99 lines, ignoring generated files. labels Oct 22, 2017

k8s-github-robot assigned jesscodez Oct 22, 2017

heidecke requested a review from chenopis October 23, 2017 09:52

jesscodez reviewed Oct 23, 2017

View reviewed changes

steveperry-53 added the Tech Review: Open Issues label Oct 23, 2017

steveperry-53 added Docs Review: Open Issues and removed Tech Review: Open Issues labels Oct 25, 2017

steveperry-53 reviewed Oct 25, 2017

View reviewed changes

heidecke added 2 commits October 27, 2017 03:04

Document jekyll includes snippets

7c8d56a

Add jekyll includes to docs home toc

924c88e

- Remove extra kubernetes home in toc

k8s-ci-robot added size/L Denotes a PR that changes 100-499 lines, ignoring generated files. and removed size/M Denotes a PR that changes 30-99 lines, ignoring generated files. labels Oct 26, 2017

jesscodez reviewed Oct 26, 2017

View reviewed changes

Fix typo

7933af1

jesscodez merged commit 82a05c1 into kubernetes:master Oct 26, 2017

heidecke deleted the document-includes branch October 26, 2017 19:27

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Document feature state includes #6000

Document feature state includes #6000

heidecke commented Oct 22, 2017 •

edited

Loading

k8sio-netlify-preview-bot commented Oct 22, 2017 •

edited

Loading

heidecke commented Oct 22, 2017

jesscodez left a comment

jesscodez Oct 23, 2017

heidecke Oct 24, 2017

jesscodez Oct 23, 2017

heidecke Oct 24, 2017

jesscodez Oct 23, 2017

heidecke Oct 24, 2017

jesscodez Oct 23, 2017

heidecke Oct 24, 2017

heidecke commented Oct 24, 2017

steveperry-53 Oct 25, 2017

steveperry-53 Oct 25, 2017

steveperry-53 Oct 25, 2017 •

edited

Loading

heidecke Oct 26, 2017

steveperry-53 Oct 25, 2017

heidecke commented Oct 26, 2017

jesscodez commented Oct 26, 2017

heidecke commented Oct 26, 2017

jesscodez Oct 26, 2017

heidecke commented Oct 26, 2017


		Read more about includes in the [Jekkyl documentation] (https://jekyllrb.com/docs/includes/).
		{% endcapture %}

Document feature state includes #6000

Document feature state includes #6000

Conversation

heidecke commented Oct 22, 2017 • edited Loading

k8sio-netlify-preview-bot commented Oct 22, 2017 • edited Loading

heidecke commented Oct 22, 2017

jesscodez left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

heidecke commented Oct 24, 2017

Choose a reason for hiding this comment

Choose a reason for hiding this comment

steveperry-53 Oct 25, 2017 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

heidecke commented Oct 26, 2017

jesscodez commented Oct 26, 2017

heidecke commented Oct 26, 2017

Choose a reason for hiding this comment

heidecke commented Oct 26, 2017

heidecke commented Oct 22, 2017 •

edited

Loading

k8sio-netlify-preview-bot commented Oct 22, 2017 •

edited

Loading

steveperry-53 Oct 25, 2017 •

edited

Loading