search

UbiquityRobotics / learn

Ubiquity Robotics Tutorials Wiki
https://learn.ubiquityrobotics.com
15 stars 13 forks source link

Documentation Overhaul #55

Closed MoffKalast closed 2 years ago

MoffKalast commented 2 years ago

For those out of the loop, this rework adds a jekyll plugin to the existing github pages which makes the end result look more like readthedocs, and also adds custom stuff like ros distro switching. While we're at it we're also merging ezmap and breadcrumb docs into it and updating/reworking the original learn docs.

View here: https://moffkalast.github.io/learn

Note to self, before merging all links hardcoded to that url need to be changed to the actual learn domain.

MoffKalast commented 2 years ago

So @mjstn I've added those redirects you requested, so old pages should get a note saying where the page moved to in case it has.

Right now there are still a few pages that I don't exactly know what to do with, mainly these:

The first one is mostly replaced by the navbar (I'll try to split the info around other pages where applicable), the other two are accessible via direct links only.

JanezCim commented 2 years ago

@MoffKalast I think it would be smart to also leave the original learn page as is for now and create a new branch that will be these changes that we are making now. Is that possible? It would be smart to keep old links working since they are spread all over internet and maybe put a large banner over them redirecting them to new docs

MoffKalast commented 2 years ago

It would be smart to keep old links working since they are spread all over internet and maybe put a large banner over them redirecting them to new docs

Already ahead of you. Mark and I discussed that before, and it was addressed in https://github.com/UbiquityRobotics/learn/pull/55/commits/7bbfa536f63c5f89f9e87ca82ad2df643ba72246.

Most of the pages look like this example: https://moffkalast.github.io/learn/unboxing

I.e. it's just a link to where the new one is. Since the old pages don't have the distro_group_name convention they don't conflict with anything and we can just keep them around to not leave broken links. Feel free to test if there's any that I missed but I think it should be all covered (except for "Introduction To The Magni Platform" and "If you don’t have your robot yet" that are now on the landing page anyway).

The ones that we're effectively deprecating are left mostly as-is, such as these:

They're all set up as hidden link-accesible pages that we can include somewhere on the main pages (robot commander is noted in "connecting to your robot" iirc) with some asterisks attached.

I think it would be smart to also leave the original learn page as is for now and create a new branch that will be these changes that we are making now. Is that possible?

Well it would be prudent to make an archival branch of the current state before the new stuff is merged (in case we want to go back and check how it used to be set up more easily than browsing through commits), but we cannot host more than one branch on github pages at a time. If we wanted to have both hosted we'd need to make a new repo and subdomain, which I'm pretty sure we don't want as it just creates confusion both for users and maintainers.

JanezCim commented 2 years ago

Already ahead of you.

https://www.meme-arsenal.com/memes/b60b8de1a1dd14a9ff622a512528bb9c.jpg

JanezCim commented 2 years ago

@MoffKalast One more comment, in VS code in preview i cant see images with the absolute paths to asset images like they are now:

image

VS code preview needs relative paths. Do you have a solution for this im missing?

MoffKalast commented 2 years ago

Hmm, well as long as those relative paths do actually work when the page is hosted feel free to find and replace all "(assets/" with "(../../assets/".

As for myself I was only previewing the pages in a locally hosted jekyll instance.

Edit: It does seem to show up fine with relative paths in the browser for me with local hosting, can you try committing your changes so far and we'll verify it works on github pages too?

JanezCim commented 2 years ago

Damn, the relative links actually work. Amazing

MoffKalast commented 2 years ago

Things that remain to be done but can wait for the initial merge:

Also there's now an archived version of the old learn accessible at https://ubiquityrobotics.github.io/learn_legacy_archive/, as a cloned repo and it can stay up when we nuke the main one.

anfederman commented 2 years ago

Hey, I tried to edit this, but it kciked me out after I spent about an hour making changes, I couldn't commit to a new branch.

On Tue, May 10, 2022 at 7:23 AM MoffKalast @.***> wrote:

Things that remain to be done but can wait for the initial merge:

-

ROS Basics need reworking to be a better introductory tutorial https://moffkalast.github.io/learn/noetic_quick_start_ros101

A new Fiducials page that would replace the legacy one https://moffkalast.github.io/learn/fiducials with STag support and a web fiducial dict generator based on UbiquityRobotics/breadcrumb_learn#35 https://github.com/UbiquityRobotics/breadcrumb_learn/issues/35

— Reply to this email directly, view it on GitHub https://github.com/UbiquityRobotics/learn/pull/55#issuecomment-1122466174, or unsubscribe https://github.com/notifications/unsubscribe-auth/ABHZ3732536N7CYQ7TPLSCDVJJWM7ANCNFSM5SZU57TQ . You are receiving this because you are subscribed to this thread.Message ID: @.***>