Move mkdocs work over from julz/mkdocs branch by julz · Pull Request #3551 · knative/docs

julz · 2021-05-11T08:10:40Z

Moves over the mkdocs work from julz/mkdocs, and re-converts serving/eventing docs to mkdocs.

This is almost entirely automated. I copied over mkdocs.yml, extra.css,
overrides/* (the home page), macros.py, index.md, and the getting started
directory and then ran the following scripts:

mkhugo to convert shortcodes to nice mkdocs markdown.
Rename _index.md to README.md where it did not contain a readfile shortcode.
h1fi to add top-level headers where missing
(looks nicer on github, and makes mkdocs material search results look nicer -- this is the
majority of the diff 🤷).
mknav to generate the nav section of the yaml
for serving and eventing based on the weights in the existing metadata (and
then a bit of manual touch-up after to make the structure a bit nicer).

Having done this - since the scripts had done all the work of converting them - I dropped the excludes
from mkdocs.yml that had been hiding most of the samples \o/.

To test, check out the branch and run mkdocs serve. You should see no errors
(other than some broken in-page links we need to fix up - these look like they're mostly missing aliases),
and you should be able to correctly click through all the pages.

All the above scripts are idempontent, so it should be fine to rerun them to
fix up any outstanding PRs that we want to cherry-pick after this.

/assign @omerbensaadon @csantanapr

avoids a directory with no index/readme

Makes things look nicer in github, and makes search work more accurately in mkdocs

omerbensaadon · 2021-05-11T11:43:43Z

Great work on this!

mknav to generate the nav section of the yaml
for serving and eventing based on the weights in the existing metadata (and
then a bit of manual touch-up after to make the structure a bit nicer).

It seems to me that the Serving section still contains some of the editorial decisions we made RE: navigation... is that meant to be there?

julz · 2021-05-11T11:47:42Z

Yeah that was the touch up I mentioned, decided it felt like a better start to create a couple folders, but I'd happily pull it out and land it separately if you like 🤷‍♂️

omerbensaadon · 2021-05-11T11:51:02Z

@julz that's ok, I can write a story to make this nav match the nav on knative.dev, just wanted to make sure this wasn't a failure of the script. Not a big lift, no worries.

omerbensaadon

Looks great for a first pass!

We've got a few things we'll need to touch up with a fine-tooth-comb in the coming weeks but this is a fantastic start.

Thanks @julz not sure how we'd do this without you!!

CC: @csantanapr

omerbensaadon · 2021-05-11T11:46:14Z

-[KafkaChannel - Consolidated](https://github.com/knative-sandbox/eventing-kafka/tree/{{< branch >}}/pkg/channel/consolidated/README.md) | Proof of Concept | None | Channels are backed by [Apache Kafka](http://kafka.apache.org/) topics. The original Knative KafkaChannel implementation which utilizes a single combined Kafka Producer / Consumer deployment.
-[KafkaChannel - Distributed](https://github.com/knative-sandbox/eventing-kafka/tree/{{< branch >}}/pkg/channel/distributed/README.md) | Proof of Concept | None | Channels are backed by [Apache Kafka](http://kafka.apache.org/) topics. An alternate KafkaChannel implementation, contributed by SAP's [Kyma](https://kyma-project.io/) project, which provides a more granular deployment of Producers / Consumers.
-[NatssChannel](https://github.com/knative-sandbox/eventing-natss/tree/{{< branch >}}/config/README.md) | Proof of Concept | None | Channels are backed by [NATS Streaming](https://github.com/nats-io/nats-streaming-server#configuring).
+[InMemoryChannel](https://github.com/knative/eventing/tree/{{ branch }}/config/channels/in-memory-channel/README.md) | Proof of Concept | None | In-memory channels are a best effort Channel. They should NOT be used in Production. They are useful for development.


Does {{ branch }} work the same was as the old {{ < branch > }} ?

Looks like it does... how?!

sort of, the old branch did some magic to get the branch via what directory it had been git cloned-ed in to during the build in processresourcefiles.sh . I think our build will be a bit less complicated so we can just use a variable defined in mkdocs.yml (but we'll fully define this when we get to building versioned docs).

omerbensaadon · 2021-05-11T12:00:42Z

+
 Tutorial on how to build and deploy a `KafkaSource` [Eventing source](../../../sources/README.md) using a Knative Serving `Service`.

 ## Prerequisites


Looks like numbering breaks using code blocks, have seen this in other places, we can take care of it during cleanup

ah yeah, I think this is slightly invalid markdown that hugo copes with better. Deleting the line above the code block solves it iirc

omerbensaadon · 2021-05-11T12:01:12Z


    ```bash
-    kubectl apply --filename {{< artifact org="knative-sandbox" repo="eventing-kafka-broker" file="eventing-kafka-controller.yaml" >}}
+    kubectl apply --filename {{ artifact(org="knative-sandbox", repo="eventing-kafka-broker", file="eventing-kafka-controller.yaml") }}


Why does this work?!

docs/hack/macros.py

Line 6 in 4738fe3

def artifact(repo, file, org="knative"):

:)

omerbensaadon · 2021-05-11T12:03:57Z

/lgtm

knative-prow-robot · 2021-05-11T12:57:56Z

[APPROVALNOTIFIER] This PR is APPROVED

Approval requirements bypassed by manually added approval.

This pull-request has been approved by: omerbensaadon

The full list of commands accepted by this bot can be found here.

The pull request process is described here

Details

Needs approval from an approver in each of these files:

OWNERS

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

csantanapr · 2021-05-11T16:13:44Z

Nice work @julz 🙌

* initial move over * Fix up index page names * Add version variables * Escape macro syntax * Automatic fixups with mkhugo * Drop no-longer-needed excludes * Rename more _index files * Move broker-configmaps.md a README.md avoids a directory with no index/readme * Autogenerate Eventing nav * Fix markdown * Update Serving nav * Add h1 headers Makes things look nicer in github, and makes search work more accurately in mkdocs * Unexclude all samples * Correct client link * Fix gitignore, skip hugo tests

julz added 14 commits May 10, 2021 16:27

initial move over

3670497

Fix up index page names

e390a23

Add version variables

005522e

Escape macro syntax

109a835

Automatic fixups with mkhugo

748110c

Drop no-longer-needed excludes

16415c0

Rename more _index files

ce9e9f9

Move broker-configmaps.md a README.md

39eb262

avoids a directory with no index/readme

Autogenerate Eventing nav

a137240

Fix markdown

b46d66b

Update Serving nav

4b2d568

Add h1 headers

ddacbe6

Makes things look nicer in github, and makes search work more accurately in mkdocs

Unexclude all samples

66d0729

Correct client link

4738fe3

knative-prow-robot assigned csantanapr and omerbensaadon May 11, 2021

knative-prow-robot added the size/XXL Denotes a PR that changes 1000+ lines, ignoring generated files. label May 11, 2021

google-cla Bot added the cla: yes Indicates the PR's author has signed the CLA. label May 11, 2021

Fix gitignore, skip hugo tests

a244425

julz force-pushed the mkmain branch from f43558d to a244425 Compare May 11, 2021 08:30

omerbensaadon approved these changes May 11, 2021

View reviewed changes

knative-prow-robot added the lgtm Indicates that a PR is ready to be merged. label May 11, 2021

omerbensaadon added the approved Indicates a PR has been approved by an approver from all required OWNERS files. label May 11, 2021

knative-prow-robot merged commit 61b8c3f into knative:mkdocs May 11, 2021

omerbensaadon mentioned this pull request May 11, 2021

Initial migration from julz/docs/mkdocs to knative/docs/mkdocs #3547

Closed

julz mentioned this pull request May 12, 2021

Regenerate the client nav #3566

Merged

omerbensaadon added the kind/mkdocs label May 12, 2021


		Tutorial on how to build and deploy a `KafkaSource` [Eventing source](../../../sources/README.md) using a Knative Serving `Service`.

		## Prerequisites

Conversation

julz commented May 11, 2021 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

omerbensaadon commented May 11, 2021

Uh oh!

julz commented May 11, 2021

Uh oh!

omerbensaadon commented May 11, 2021

Uh oh!

omerbensaadon left a comment

Choose a reason for hiding this comment

Uh oh!

omerbensaadon May 11, 2021

Choose a reason for hiding this comment

Uh oh!

omerbensaadon May 11, 2021

Choose a reason for hiding this comment

Uh oh!

julz May 11, 2021 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

omerbensaadon May 11, 2021

Choose a reason for hiding this comment

Uh oh!

julz May 11, 2021 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

omerbensaadon May 11, 2021

Choose a reason for hiding this comment

Uh oh!

julz May 11, 2021 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

omerbensaadon commented May 11, 2021

Uh oh!

knative-prow-robot commented May 11, 2021

Uh oh!

csantanapr commented May 11, 2021

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

julz commented May 11, 2021 •

edited

Loading

julz May 11, 2021 •

edited

Loading

julz May 11, 2021 •

edited

Loading

julz May 11, 2021 •

edited

Loading