docs: refactor to use mdbook instead of wiki [Work in Progress]

[dwalkes]

This PR is not yet ready to merge but creating here as a starting point for discussion and likely place for a discussion in the upcoming meeting

• For working site demo, see https://oe4t.github.io/master/
• For any pull requests before initial merge, especially for remaining tasks 1-5 below, you can target corresponding branches at https://github.com/trellis-logic/meta-tegra

Remaining tasks:

1. Get the master branch [SUMMARY.md](https://github.com/Trellis-Logic/meta-tegra/blob/master/docs/SUMMARY.md) and any other content matching the preferred layout for all branches.
2. Update commit series on https://github.com/Trellis-Logic/meta-tegra/tree/scarthgap to include content from master branch.
3. Cherry commit(s) from scarthgap branches to any other branches we want documentation files deployed to (probably at least scarthgap-l4t-r35.x, maybe also kirkstone, and kirkstone-l4t-r32.7.x)
4. Update version file at https://github.com/OE4T/oe4t.github.io/blob/main/versions.json to list all branches supported.
5. Remove content from branches which are not applicable and make the docs branch content diverge from each other (can also be done later after merge to oe4t)
6. Update the meta-tegra repo to include actions repository secret OE4T_GITHUB_DEPLOY_KEY - either get from Dan or Generate yourself.

• If generating yourself, add the public deploy key at https://github.com/OE4T/oe4t.github.io/settings/keys

7. Remove the deploy key from Dan's repo to avoid accidental pushes from his meta-tegra repo.
8. Merge changes from each of the branches in https://github.com/OE4T/oe4t.github.io/blob/main/versions.json into the meta-tegra repo.
9. Replace each of the wiki files content at https://github.com/OE4T/meta-tegra/wiki which are listed in the summary file at https://github.com/Trellis-Logic/meta-tegra/blob/master/docs/SUMMARY.md with links to the master version of the documentation site

• Exclude OE4T-Meeting*
• Exclude ZZZ*

The wiki content for this page has been replaced with the content at https://oe4t.github.io/master/link-to-page Please refer to the content of the master branch as older branches may be out of date

[cbrake]

Looking good!

I added a doc workflow page, so I could understand how it works - very nice setup:

Trellis-Logic#4

[cbrake]

One thing I typically enforce on my projects is markdown formatting.

• create a script in the repo that wraps to 80 char and format with prettier.
• a CI tasks that checks that all docs have been formatted.

Like with code, this helps ensure consistent formatting and minimizes merge hassles. If this sounds OK, I can add this.

[dwalkes]

@cbrake thanks for the suggestions and changes, please do add whatever you've found useful.

[dwalkes]

I've updated to use the OE4T repo for docs at https://github.com/OE4T/oe4t.github.io as discussed in the meeting, and made changes to the documentation workflow to describe the new setup, also updated the remaining steps above.

I'm still struggling with exactly how to move the "Which branch should I use" page and yet keep release notes on branches. We discussed in the last monthly meeting only moving the Which branch should I use page to the master branch but keeping release notes on individual branches.

• If we move "Which branch should I use" to the master branch we either need to have stale copies of this page on old branches forked from master or remember to delete when we create a branch off master.

  • I'm assuming we don't want stale copies so should probably delete.
  • If we do delete we won't be able to backport merges of new releases to old branches, or at least this part of the merge will fail.

• If we keep release note copies on old branches, we either need the workflow to be to delete any release notes on a branch when forking and update all references to be on the master branch, or we will have stale copies of release notes on old branches.

  • Consider for example the fact that the scarthgap and master branch both reference https://github.com/OE4T/meta-tegra/wiki/JetPack-6.2.1-L4T-R36.4.4-Notes.
    • If we keep release notes on individual branches we either need to keep a duplicate copy of these release notes on each branch OR we need the scarthgap branch to reference master, and we need to update the scarthgap branch to reference the new master release notes on each change.
    • If we delete release notes on old branches, we'll lose release history of intermediate releases on the docs site, and the only way to find them will be to roll back to branch history. I'm guessing this would be less desirable, so we'll need to take care to avoid removing release history when it is no longer supported on parent branches, so the release notes are still visible on the docs site.
      • I'm assuming we'll want to always reference the newer branch as long as a release is supported on a newer branch, and avoid duplicate copies where possible?
      • If a release stops being supported on a newer branch, however, we'll break the link when we remove it from the newer branch, so we will need the rule to be to always keep the release history of a given branch on that branch.

It seems the ideal workflow would be that when you backport a release from new branch to old branch you can just apply all the commits, including docs commits, to the old branch. That would mean we'll keep multiple copies of the release notes on each branch, and if we update the release notes between backports we need to remember to also backport the release note patches or we'll have one of the copies out of date.

This feels like we need either:

1. Automated checks or ideally copies to move files where they should go on the docs site or warn you when you are making stuff out of date.
2. Some type of logic on the docs site to try to select the best branch for release notes or "which branch" pages, based on the latest branch where the content exists.
   or
3. Keep which branch and release notes pages on the wiki.

Am I overthinking this?

[madisongh]

How about we update the "Which branch should I use" page so that it has a link on it to the copy that is generated off the master branch (along with some text to say "click here for the latest version" or some such)? Then we can just do copies for back-ports, the copy of that page would be a snapshot, but there would always be a link to latest available.

BTW, I took a quick look at https://oe4t.github.io - looks great!

[dwalkes]

OK that direction makes sense to me, essentially we prioritize keeping backports of documentation pain-free at the expense of possibly having out of date and duplicate information on old branches. I think it would not be too difficult to add a warning banner on all pages other than master to state that documentation may be out of date, similar to what openembedded and other projects use. I haven't tried to implement that yet.

I did pull in all the release notes, which branch should I use and updated all the content to reflect the latest on the wiki as of today, including some changes for link resolution. I think this is pretty close for both these two branches.

When we are ready to pull the trigger on this I think I can replace every wiki page (other than meeting notes and archived) with some text like this:

The wiki content for this page has been replaced with the content at https://oe4t.github.io/master/link-to-page Please refer to the content of the master branch as older branches may be out of date

Should we organize the docs into subdirectories instead of just a flat tree? Might be good for release notes at least.

The symlinks back to README and CONTRIBUTING files are a little odd and mean that we can't link to other documentation pages from these easily. Would probably be better to move the main copy into the docs dir and make the symlink exist in the base repo but I'm not sure you want to do that, especially for the README. Let me know if you'd like changes beyond this.

I've updated the summary to list the remaining steps. Let me know if you'd like me to do anything different with commit history on the master or scarthgap branches. Otherwise I think those are both ready to go, pending the questions above and comment in the summary of this ticket. I'll backport to all other branches and create PRs for whatever else you want too, just let me know.

[dwalkes]

Oh one other change I could make could be to try to make the docs github actions only run when the content in the docs directory changed, that might be a good thing to do too. Need to also include README.md and CONTRIBUTING.md files pending the discussion about symlinks above.

[madisongh]

The symlinks back to README and CONTRIBUTING files are a little odd and mean that we can't link to other documentation pages from these easily. Would probably be better to move the main copy into the docs dir and make the symlink exist in the base repo but I'm not sure you want to do that, especially for the README. Let me know if you'd like changes beyond this.

The README.md in the top directory has to remain exactly as it is - the Yocto layer checks expect to see specific content there. Likewise for SECURITY.md. The CONTRIBUTING file can be moved, though.

I think the front page of the documentation web site should be more of a general intro to the overall project and a maybe navigation guide for the documentation, rather than what's in the README. We can sort out the details once the overall structure is in place, though.

Thanks!

[dwalkes]

The README.md in the top directory has to remain exactly as it is - the Yocto layer checks expect to see specific content there. Likewise for SECURITY.md. The CONTRIBUTING file can be moved, though.

Makes sense, I think as long as I leave one there I may as well leave them both but let me know if you have a different preference.

I think the front page of the documentation web site should be more of a general intro to the overall project and a maybe navigation guide for the documentation, rather than what's in the README. We can sort out the details once the overall structure is in place, though.

Also makes sense. mdbook requires the README.md to be the landing page so I've repurposed to match the Home.md file content from the existing wiki as a starting point. Let me know if you have something different in mind.

I also reorganized the release notes a bit to try to remove some of the clutter and added the github actions filter to avoid re-running the workflow when there weren't docs changes.

What else would you like me to do on this one? Backport as-is to other current branches? Make some additional content changes first?