Docs: Updated Custom Filters

[markmandel]

Updates the custom filter documentation to the latest API changes.

This also includes using mdbook's include preprocessor to inject the example code into the documentation.

Note: Because of the use of include preprocessor I had to remove the Markdown lists, as they wouldn't format correctly
(See: rust-lang/mdBook#1564).

Closes #373

[markmandel]

Just noting: Since I had to remove the lists, I moved the headers to be in level order. PTAL, let me know what you think.

[markmandel]

I couldn't include this, so just copied it inline. In theory it could go out of date, but I couldn't think of a better way.

[markmandel]

This should no longer apply, as now it matches how it was before.

[markmandel]

Looks like I broke a stack of the docs tests. I'll swing back to this tomorrow and see if I can fix them / if they should be ignored.

[quilkin-bot]

Build Failed 😭

Build Id: 004feda8-538d-4908-bac5-ba04e2f4f23f

Status: FAILURE

• Cloud Build view
• Cloud Build log download

To get permission to view the Cloud Build view, join the quilkin-discuss Google Group.

[iffyio]

I don't think this is correct? the factory() function or constructor wouldn't be visible at all from user code and what's passed into quilkin is the DynFilterFactory so it doesn't matter how the object is generated?

Suggested change

	> As a convention we implement a `pub factory() -> DynFilterFactory` function, to
	> make the next integration step easier.

[markmandel]

Just so I'm clear, are you saying the description isn't correct?

If I look at all our Filter implementations, they all have a pub factory() -> DynFilterFactory - so I thought it would be good to call out that we conventionally do that, and why.

You are 100% correct that the end use could create a constructor any way, but I thought it would be good to show our usual convention. Maybe the description should be:

As a convention we generally implement a pub factory() -> DynFilterFactory function as a constructor, but a Factory
can be constructed as you see fit.

To explain that while you may see this common pattern, it's more by convention, rather than technical limitation. WDYT?

[iffyio]

Ah, the incorrect part was mostly the 'to make the next integration step easier' bit since the function itself didn't matter.

I think in this case the fact that the quilkin codebase used a function called factory vs anything else doesn't matter at all so it can add confusion to call it out in the first place (as a user I'd find myself reading into what that means and quickly realise it doesn't matter which is wasted time), the user would declare and call the function within their own crate so the function can be called anything or they could construct the factory by some other means (I don't see it as a convention here since both crates don't need to worry about it in the first place).

[markmandel]

That's fair. Sounds good, I'll remove the comment 👍🏻

Worst case, if people start asking, we can add it back in 😄

[markmandel]

Updated, so now it should pass -- basically put the include sections back the way they were before, and updated the include sections so that they have a // src/main.rs (or similar) comment like they did previously.

Also updated the initial examples include to use use quilkin::filters::prelude::*; - since that is also what we're generally using now as well.

[quilkin-bot]

Build Succeeded 🥳

Build Id: 30356946-5915-4913-8bcc-8c8b45b8869b

To build this version:

git fetch git@github.com:googleforgames/quilkin.git pull/395/head:pr_395 && git checkout pr_395
cargo build

[quilkin-bot]

Build Succeeded 🥳

Build Id: 6261f220-b1b4-443f-8e29-bdcba19d3897

To build this version:

git fetch git@github.com:googleforgames/quilkin.git pull/395/head:pr_395 && git checkout pr_395
cargo build

[quilkin-bot]

Build Succeeded 🥳

Build Id: 43e02ee7-7ae8-448d-b4f5-a7f1f97dfd4f

To build this version:

git fetch git@github.com:googleforgames/quilkin.git pull/395/head:pr_395 && git checkout pr_395
cargo build