Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

CI: link checking on documentation #367

Closed
markmandel opened this issue Aug 13, 2021 · 2 comments · Fixed by #445 or #449
Closed

CI: link checking on documentation #367

markmandel opened this issue Aug 13, 2021 · 2 comments · Fixed by #445 or #449
Labels
area/build-tools Development tooling. kind/documentation Improvements or additions to documentation kind/feature New feature or request

Comments

@markmandel
Copy link
Contributor

We should have a link checker that traverses both our mdbook generated documentation as well as the rustdoc generated documentation.

I expect we'll have both sets of documentation pointing at each other (we do in #363), so I posit that it would be good to use a tool that can cover both doc sets at the same time to make sure they work appropriately.

I've used https://github.com/wjdp/htmltest in the past - I like that it caches external links for 2 weeks (configurable), especially since github can get particularly cranky if you make requests against it too often. I've previously cached this between builds as well, as well as implemented more retries in Agones if we want to use the same thing (source).

But definitely open to other tools!
@markmandel markmandel added kind/documentation Improvements or additions to documentation kind/feature New feature or request area/build-tools Development tooling. labels Aug 13, 2021
@markmandel markmandel mentioned this issue Aug 13, 2021
Merged
@markmandel markmandel mentioned this issue Aug 25, 2021
Closed
markmandel added a commit to markmandel/quilkin that referenced this issue Aug 25, 2021
@markmandel
Fix 404: Writing Custom Filters
618f0f9 
This should give me impetus to complete googleforgames#367 since I just checked all
the links by hand.

Noticed that on local `make docs` you can go extra levels deep on `../`
relative links, and they still work locally, but not online.

Anyway, fixed all that up now, so the links aren't 404'd.

Work on googleforgames#373
@markmandel markmandel mentioned this issue Aug 25, 2021
Merged
markmandel added a commit that referenced this issue Aug 25, 2021
@markmandel
Fix 404: Writing Custom Filters (#376)
93f2f72 
This should give me impetus to complete #367 since I just checked all
the links by hand.

Noticed that on local `make docs` you can go extra levels deep on `../`
relative links, and they still work locally, but not online.

Anyway, fixed all that up now, so the links aren't 404'd.

Work on #373
@markmandel
Copy link
Contributor Author

Got this in the works. I had to fix an issue with htmltest, so will have a PR with a bunch of 404 fixes coming, and if it doesn't get merged soon, I'll install from my fork's source.

@markmandel markmandel mentioned this issue Nov 24, 2021
Closed
markmandel added a commit to markmandel/quilkin that referenced this issue Nov 24, 2021
@markmandel
Docs: Fix broken links
2618bca 
This fixes for all the broken links I found while working on googleforgames#367.

Next PR to close googleforgames#367 will include automated testing of the
documentation, just waiting to see if a bug fix I have in PR will flow
through in a timely manner. If not, will install in our build image from
my fork with the fixes.
@markmandel markmandel mentioned this issue Nov 24, 2021
Merged
XAMPPRocky pushed a commit that referenced this issue Nov 26, 2021
@markmandel
Docs: Fix broken links (#445)
8773320 
This fixes for all the broken links I found while working on #367.

Next PR to close #367 will include automated testing of the
documentation, just waiting to see if a bug fix I have in PR will flow
through in a timely manner. If not, will install in our build image from
my fork with the fixes.
@markmandel
Copy link
Contributor Author

Accidentally closed this by writing "will close" forgetting that Github would auto close things.

@markmandel markmandel reopened this Nov 29, 2021
markmandel added a commit to markmandel/quilkin that referenced this issue Nov 30, 2021
@markmandel
CI: Documentation test gen, links, images, etc.
9d9b9b2 
Introduces both building the documentation sites with `mdbook` and
`cargo doc` as well as placing them in the same directory structure as
they exist in on GitHub pages.

Utilising `htmltest` to test the links, images, scripts etc in the
`mdbook` pages (there are lots of invalid anchors in the rustdoc, so not
 testing the links for now - but we could later).

To use locally: `make test-docs` will run the tests for you.

Extra notes:
* Had to use a fork of `htmltest`, as awaiting the merging of a critical
  bugfix.
* Split up each of the test targets in `cloudbuild.yaml`. This requires
  a bit more work when writing new test targets in the Makefile, but
  will be easier to determine why things go wrong in CI.
* Broke up the Dockerfile into sections, to make it faster for local
  rebuilding.

Fix googleforgames#367
@markmandel markmandel mentioned this issue Nov 30, 2021
Merged
markmandel added a commit to markmandel/quilkin that referenced this issue Nov 30, 2021
@markmandel
CI: Documentation test gen, links, images, etc.
da7365e 
Introduces both building the documentation sites with `mdbook` and
`cargo doc` as well as placing them in the same directory structure as
they exist in on GitHub pages.

Utilising `htmltest` to test the links, images, scripts etc in the
`mdbook` pages (there are lots of invalid anchors in the rustdoc, so not
 testing the links for now - but we could later).

To use locally: `make test-docs` will run the tests for you.

Extra notes:
* Had to use a fork of `htmltest`, as awaiting the merging of a critical
  bugfix.
* Split up each of the test targets in `cloudbuild.yaml`. This requires
  a bit more work when writing new test targets in the Makefile, but
  will be easier to determine why things go wrong in CI.
* Broke up the Dockerfile into sections, to make it faster for local
  rebuilding.

Fix googleforgames#367
markmandel added a commit that referenced this issue Dec 1, 2021
@markmandel
CI: Documentation test gen, links, images, etc. (#449)
cbda4f4 
Introduces both building the documentation sites with `mdbook` and
`cargo doc` as well as placing them in the same directory structure as
they exist in on GitHub pages.

Utilising `htmltest` to test the links, images, scripts etc in the
`mdbook` pages (there are lots of invalid anchors in the rustdoc, so not
 testing the links for now - but we could later).

To use locally: `make test-docs` will run the tests for you.

Extra notes:
* Had to use a fork of `htmltest`, as awaiting the merging of a critical
  bugfix.
* Split up each of the test targets in `cloudbuild.yaml`. This requires
  a bit more work when writing new test targets in the Makefile, but
  will be easier to determine why things go wrong in CI.
* Broke up the Dockerfile into sections, to make it faster for local
  rebuilding.

Fix #367
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
area/build-tools Development tooling. kind/documentation Improvements or additions to documentation kind/feature New feature or request
Projects
None yet
Milestone
No milestone
1 participant
@markmandel