Update doc links #363

iffyio · 2021-08-12T11:09:17Z

Updated missing links in docs.

For links to api references I imagine we don't want to hardcode the version and instead set that based on the current version? for now though I link to the current version since it doesn't seem there's a simple way to do that with mdbook. I found this that we might need to use https://crates.io/crates/mdbook-variables - it sets variables that's substituted during doc generation - though I had to update it locally to get it to work since its using a pretty old mdbook crate.

Also it seems something about the current deployed docs is broken when rendering rust code blocks: check this for example
https://googleforgames.github.io/quilkin/main/book/filters/capture_bytes.html#configuration-examples
that should only show the yaml and the rust bits should be hidden, it renders properly though when I build locally so maybe we've done something special with the deployed one

XAMPPRocky · 2021-08-12T11:37:46Z

docs/src/filters/writing_custom_filters.md

+[Filter]: https://docs.rs/quilkin/{{version}}/quilkin/filters/trait.Filter.html
+[FilterFactory]: https://docs.rs/quilkin/0.1.0/quilkin/filters/trait.FilterFactory.html
+[filter-factory-name]: https://docs.rs/quilkin/0.1.0/quilkin/filters/trait.FilterFactory.html#tymethod.name
+[FilterRegistry]: https://docs.rs/quilkin/0.1.0/quilkin/filters/struct.FilterRegistry.html
+[runner::run]: https://docs.rs/quilkin/0.1.0/quilkin/runner/fn.run.html
+[CreateFilterArgs::config]: https://docs.rs/quilkin/0.1.0/quilkin/filters/prelude/struct.CreateFilterArgs.html#structfield.config
+[ConfigType::dynamic]: https://docs.rs/quilkin/0.1.0/quilkin/filters/enum.ConfigType.html#variant.Dynamic


This is why I think we should move this stuff to rustdoc, it would always go to the correct version.

We can also just use relative links to our local versions of the API docs - since they are published together.

They aren't published together at mdbook build/test time though, so that would fail any linkchecking.

We could also use a seperate link checker - we don't have to be tied just to mdbook's link checker - then we can check links across the entire documentation set. This will be particularly useful as we will probably end up with links going back and forth between rustdoc and mdbook.

I'm particularly partial to https://github.com/wjdp/htmltest for link checking across an entire website.

Created #367 to track the discussion!

markmandel · 2021-08-12T22:13:13Z

docs/src/filters/writing_custom_filters.md

-[runner]: #
-[create-filter-args-config]: #CreateFilter::config
-[config-type-dynamic]: #ConfigType::Dynamic
+[Filter]: https://docs.rs/quilkin/0.1.0/quilkin/filters/trait.Filter.html


So that it always stays inline with the released version, we can link directly to our local versions of the api docs, but relatively.

Suggested change

[Filter]: https://docs.rs/quilkin/0.1.0/quilkin/filters/trait.Filter.html

[Filter]: ../../api/quilkin/filters/trait.Filter.html

(I think that's the right number of redirects, might want to confirm on the gh-pages branch)

And repeat as per below.

Then we never have to update the version 🙂

Because of this, created #365 - to make it easier to preview this locally.

do we have any means of versioning what we deploy with mdbook? e.g if we release a 0.2.0 and later a 0.3.0 as far as the mdbook doc is concerned 0.2.0 version no longer existed right? or is that kept around still?

Yep! @XAMPPRocky did an awesome job there - the github action runs on each tag run (source), and grabs the tag/branch name and makes it the parent folder (so development is in main, but when we make a v0.2.0 release we'll get a v0.2.0 parent folder).

I tested it out on a fork, and it worked super nice 👍🏻

I had some updates to the documentation I wanted to make, but I wanted to be able to preview the whole documentation set created by `cargo doc` and `mdbook` in the the same directory structure as we have it hosted on Github pages. Also, I saw googleforgames#363. So with some extra components in our build image, and a combination of `cargo watch` and a python dev library that hosts the files, and hot reloads on changes for all documentation, we have a nice local tool for writing and previewing documentation locally! Closes googleforgames#365

I had some updates to the documentation I wanted to make, but I wanted to be able to preview the whole documentation set created by `cargo doc` and `mdbook` in the the same directory structure as we have it hosted on Github pages. Also, I saw #363. So with some extra components in our build image, and a combination of `cargo watch` and a python dev library that hosts the files, and hot reloads on changes for all documentation, we have a nice local tool for writing and previewing documentation locally! Closes #365

markmandel

Pulled this down and ran a local preview, found a few broken links (Hence #367)

I was hacking away to work out what was needed to be fixed, so I added suggestions below, but I attached a patch if you want to have all my changes.
docs.patch.txt

(Can also grab it on this branch)

markmandel · 2021-08-13T19:17:30Z

docs/src/filters/writing_custom_filters.md

+[FilterRegistry]: ../../../api/quilkin/0.1.0/quilkin/filters/struct.FilterRegistry.html
+[runner::run]: ../../../api/quilkin/0.1.0/quilkin/runner/fn.run.html
+[CreateFilterArgs::config]: ../../../api/quilkin/0.1.0/quilkin/filters/prelude/struct.CreateFilterArgs.html#structfield.config
+[ConfigType::dynamic]: ../../../api/quilkin/0.1.0/quilkin/filters/enum.ConfigType.html#variant.Dynamic


Suggested change

[ConfigType::dynamic]: ../../../api/quilkin/0.1.0/quilkin/filters/enum.ConfigType.html#variant.Dynamic

[ConfigType::dynamic]: ../../../api/quilkin/filters/enum.ConfigType.html#variant.Dynamic

(Also this type doesn't exist anymore, but that may be a problem for another day).

markmandel · 2021-08-13T19:18:39Z

docs/src/filters/writing_custom_filters.md


 [anchor-static-config]: #static-configuration
-[Filters]: ./filters.md
+[Filters]: ../filters.md


This change to .. needs to be applied to all the below links that also point to filters.md.

markmandel · 2021-08-13T19:20:22Z

docs/src/filters/writing_custom_filters.md

-[config-type-dynamic]: #ConfigType::Dynamic
+[Filter]: ../../../api/quilkin/filters/trait.Filter.html
+[FilterFactory]: ../../../api/quilkin/filters/trait.FilterFactory.html
+[filter-factory-name]: ../../../api/quilkin/0.1.0/quilkin/filters/trait.FilterFactory.html#tymethod.name


Suggested change

[filter-factory-name]: ../../../api/quilkin/0.1.0/quilkin/filters/trait.FilterFactory.html#tymethod.name

[filter-factory-name]: ../../../api/quilkin/filters/trait.FilterFactory.html#tymethod.name

Don' t need to specify the version, it all gets bundled up under the the same parent directory, which has the version snapshot.

markmandel · 2021-08-13T19:22:35Z

docs/src/xds.md

 [listener-resource]: https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/listener/v3/listener.proto#config-listener-v3-listener
 [xds-filters]: https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/listener/v3/listener_components.proto#envoy-v3-api-msg-config-listener-v3-filter
 [xds-filter-chain]: https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/listener/v3/listener_components.proto#config-listener-v3-filterchain
 [DiscoveryRequest]: https://www.envoyproxy.io/docs/envoy/latest/api-v2/api/v2/discovery.proto#envoy-api-msg-discoveryrequest
 [xds-variants]: https://www.envoyproxy.io/docs/envoy/latest/api-docs/xds_protocol#variants-of-the-xds-transport-protocol
-[filter-protos]: ../proto/quilkin/extensions/filters
-[filters-doc]: ./extensions/filters/filters.md
+[filter-protos]: https://github.com/googleforgames/quilkin/tree/v0.1.0/proto/quilkin/extensions/filters


🤔 should we point at main, rather than the version? We could add a note in the docs that you would want to choose the release tagged version when importing?

Save us updating the docs on each release?

Update doc links

d578695

iffyio requested review from markmandel and XAMPPRocky August 12, 2021 11:09

google-cla bot added the cla: yes label Aug 12, 2021

github-actions bot added the size/s label Aug 12, 2021

XAMPPRocky approved these changes Aug 12, 2021

View reviewed changes

remove test variable

adb035b

markmandel mentioned this pull request Aug 12, 2021

Build: make docs to preview documentation locally #365

Closed

markmandel reviewed Aug 12, 2021

View reviewed changes

markmandel mentioned this pull request Aug 13, 2021

make docs to preview documentation locally #366

Merged

use relative paths

a0ec19c

Merge branch 'main' into iu/doc-links

c35d0fc

markmandel mentioned this pull request Aug 13, 2021

CI: link checking on documentation #367

Closed

markmandel reviewed Aug 13, 2021

View reviewed changes

iffyio added 2 commits August 16, 2021 12:16

fix links

7b6c92a

link to protos on main

33c44b3

iffyio requested a review from markmandel August 16, 2021 10:22

markmandel approved these changes Aug 17, 2021

View reviewed changes

Merge branch 'main' into iu/doc-links

34490cc

XAMPPRocky merged commit 364df25 into main Aug 17, 2021

markmandel deleted the iu/doc-links branch August 17, 2021 18:37

markmandel added kind/cleanup Refactoring code, fixing up documentation, etc kind/documentation Improvements or additions to documentation labels Sep 21, 2021

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Update doc links #363

Update doc links #363

iffyio commented Aug 12, 2021

XAMPPRocky Aug 12, 2021

markmandel Aug 12, 2021

XAMPPRocky Aug 13, 2021

markmandel Aug 13, 2021

markmandel Aug 13, 2021

markmandel Aug 12, 2021

iffyio Aug 13, 2021

markmandel Aug 13, 2021

iffyio Aug 16, 2021

markmandel left a comment

markmandel Aug 13, 2021

markmandel Aug 13, 2021

markmandel Aug 13, 2021

markmandel Aug 13, 2021

	[Filter]: https://docs.rs/quilkin/0.1.0/quilkin/filters/trait.Filter.html
	[Filter]: ../../api/quilkin/filters/trait.Filter.html

	[ConfigType::dynamic]: ../../../api/quilkin/0.1.0/quilkin/filters/enum.ConfigType.html#variant.Dynamic
	[ConfigType::dynamic]: ../../../api/quilkin/filters/enum.ConfigType.html#variant.Dynamic

	[filter-factory-name]: ../../../api/quilkin/0.1.0/quilkin/filters/trait.FilterFactory.html#tymethod.name
	[filter-factory-name]: ../../../api/quilkin/filters/trait.FilterFactory.html#tymethod.name

Update doc links #363

Update doc links #363

Conversation

iffyio commented Aug 12, 2021

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

markmandel 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