implement documentation syncing with containerd/containerd and on-site rendering

[haddscot]

addresses #163
built on top of #121

this PR implements:

• tools/refresh-docs.sh -- script to be called by Makefile [make refresh-docs – also made it a dependency of make serve and make *-build]
• .github/workflows/sync-documentation.yml -- github workflow to call make refresh-docs on a cron schedule of daily at 3am, same as sync-releases.yml. currently set to operate as a pull request, and will currently generate doc sync PR on any other PR creation for the sake of demonstration, but will remove the on: pull_request: ... before merging
• themes/containerd/layouts/partials/sidebar.html and nested-menu-partial.html -- adapted from hugocodex Auto-collapsing menu, enables browsing documentation

[estesp]

Looking at the preview here: https://deploy-preview-214--containerd-io.netlify.app/

This is promising progress, but I wonder how we can clean up the footer as shown in the below screen capture? Looks like these are directory names and are listed once for each file in the dir?

[haddscot]

Looking at the preview here: https://deploy-preview-214--containerd-io.netlify.app/

This is promising progress, but I wonder how we can clean up the footer as shown in the below screen capture? Looks like these are directory names and are listed once for each file in the dir?

I didn't even notice that, tunnel visioning on the body content.

will replace with links to docs home and the readme and getting started pages for 1.7.x and 1.6.x

[haddscot]

shortfalls that should be addressed in followup tasks:

• images that are linked relative to the file structure of the markdown must be linked relative to the root of the containerd/containerd project, so that when they are rendered to html they will be linked relative to the corresponding v... directory [e.g. v1.7.x]. for example:

the architecture diagram on the 1.7.x README renders because it is linked as ![architecture](docs/historical/design/architecture.png) in the markdown, which is a path relative to the root of the project
the architecture diagram does not render at /docs/v1.7.x/docs/historical/design/architecture/ because it is linked as ![Architecture](architecture.png) in the markdown, which is a link relative to the /docs/historical/design/ directory and not the root of the project.

• images that are in the repo but not in the docs/ directory aren't currently synced:

see the architecture diagram on the 1.6.x README which was in the design/ directory for that release.

• in today's community call, we discussed the possibility of the auto-generated title pages that are used to give the sidebar navigation menu its hierarchical structure and dropdown names could potentially be fully fleshed out sub-READMEs.
• using the weight md header, we could order the docs in the sidebar in a more logical way, so that the Getting Started page isn't listed 4th under docs/ because of the default alphabetization

[haddscot]

pinging @kzys @chalin since you both worked on the previous iterations of this task

[chalin]

Great to see progress on #163!

A few drive-by comments:

1. As mentioned in Host documentation on the website, rather than linking to GH repo #163, I strongly suggest option (1), because it is simplest. Failing that, option (2): use git submodules.

   What is proposed here feels like a custom (and deferred) kind of git "submodules", that will make it challenging to have reproducible builds.

2. Can you find a way to avoid having "docs" in doc page paths? E.g. /docs/v1.6.x/getting-started/ rather than /docs/v1.6.x/docs/getting-started/.

3. Switching to use Docsy might make your lives easier when it comes to managing doc versions.

/cc @natedoubleu @caniszczyk

[chalin]

Unless you really need Hugo 0.123.7, I'd suggest that you upgrade the Hugo version separately to have having too many moving parts. Hugo 0.123.x has a rewritten core, and they're still ironing out the bugs, e.g., see open-telemetry/opentelemetry.io#4064.

[haddscot]

I just needed to upgrade to 0.116.0+ to access the "like" operator on the "where" function

is there a version you would recommend?

[haddscot]

gonna use 0.122.0 0.116.0 for now since it's the last release before the rewritten core, and because newer versions run into weird errors building jquery

[chalin]

You might want to use /docs/latest and define a redirect rule that refers back to the latest version.

[haddscot]

A few drive-by comments:

1. As mentioned in Host documentation on the website, rather than linking to GH repo #163, I strongly suggest option (1), because it is simplest. Failing that, option (2): use git submodules.
   What is proposed here feels like a custom (and deferred) kind of git "submodules", that will make it challenging to have reproducible builds.

✅ rewrote refresh-docs.sh to use submodules instead

2. Can you find a way to avoid having "docs" in doc page paths? E.g. /docs/v1.6.x/getting-started/ rather than /docs/v1.6.x/docs/getting-started/.

I could, but the reason I did it this way is because of the relative links to images and other pages in the original markdown – see the first example here. maintaining the directory structure – i.e. treating https://containerd.io/docs/v{$X_VERSION}.x/ as equivalent to the containerd project root – prevents us from having to do changes the links in the markdown

3. Switching to use Docsy might make your lives easier when it comes to managing doc versions.

can you clarify what specifically you mean when you say "managing doc versions"? the way I see it, this change doesn't add any responsibility of managing doc versions to the .io repo beyond simply updating to whatever the latest changes are on the specified branches of the containerd repo on a daily cadence.

[haddscot]

squashed everything up to this point because of trailing whitespace errors in the CI job