Vitepress test branch

[hamishwillee]

This is an initial test build of vitepress build of MAVSDK. You can test it by cloning, and in the root of the installation running

yarn install
yarn build

Then navigate to suggested URL.

It Fixes up sidebars and nav.

Things to do:

• CI
• Fix C++ ref generation to fix up notes/tips/warnings.
• Fix up C++ ref generation or docs to fix errors that I manually "tuned" in 462782e
• Fix up other notes.

@julianoes Have peak when you get a chance. If you think it is more or less heading in the right direction then we can push it further.

[julianoes]

Thanks @hamishwillee.

What am I doing wrong?

yarn install
00h00m00s 0/0: : ERROR: [Errno 2] No such file or directory: 'install'

Edit: ah presumably I need to install npm and yarn and what not.

[hamishwillee]

Yes, that's right. D

Note that this is "somewhat deprecated" in favour of mavlink/MAVSDK#2490 since you want to have this as part of the main repo.

That is waiting on me being able to build the latest main - which as we discussed some weeks ago was failing due to open ssl issues. Were those resolved, or is it still just me?

[julianoes]

Ok, I'll check over there. I was hesitating to move it over because we need to have it for 3 versions, and I was wondering whether that's possible in the main repo.

[hamishwillee]

You can have it for three versions in the main repo. The thing is though, if you want to modify the docs in a particular version later, they will need their own branch, just as you would for code changes. I think you're mostly working with tags for versions now - right?

EDIT The thing to realize here is that the sources change, but the generated docs do not - the sources that are published are in a separate publication branch that uses a folder structure to separate the versions.

[julianoes]

We have a branch per major version, so v1, v2, and I'm going to create a v3 as well to not confuse it with main.

[julianoes]

Do I understand it right that assuming an external repo (like this), we would generate from the v1, v2, v3 branches and create the docs in 3 subfolders here.

If it was within the same repo, then we need some sort of pipeline set up that would get the v1, v2, v3 branches, auto-generate from each, and then combine it in a subsequent step?

[hamishwillee]

Nearly.

So the deployment is to https://github.com/mavlink/mavsdk.mavlink.io and we use exactly the same process as currently. When we do a build of branch "X" we delete the X folder, and recreate it with a new build of the respective branch. The other branches remain unchanged.

The deploy will be based on the PX4 one, which does this https://github.com/PX4/PX4-user_guide/blob/main/.github/workflows/docs_deploy.yml#L82-L96

The actual target of the deployment is that separate repo.

make sense?

I could set this up now, but I'd like to be sure the reference builds properly first.

[julianoes]

Ok, I think that could work, and basically would work from the main MAVSDK repo as well.

[hamishwillee]

Yes it will work from anywhere because sources and deployment are always separated. The benefit is that we don't have to rebuild the old versions with the new toolchain, we can just start from main.

Note that the new toolchain does have one irritation though. The version switcher is hard coded in each build, while in github the versions are fetched from book.json in main. So as we add new builds we will have to update the old builds to include the new version.