Update: Gitbook user guide. Issue #764

shashank40 commented 1 week ago

/claim #764

What kind of change does this PR introduce?

Gitbook User Documentation Update

Summary

As the user guide on Gitbook was old & new features were added to OpenAdapt. The documentation needed a rework with images.

Checklist

[x] My code follows the style guidelines of OpenAdapt
[x] I have performed a self-review of my code
[ ] If applicable, I have added tests to prove my fix is functional/effective
[ ] I have linted my code locally prior to submission
[ ] I have commented my code, particularly in hard-to-understand areas
[ ] I have made corresponding changes to the documentation (e.g. README.md, requirements.txt)
[ ] New and existing unit tests pass locally with my changes

How can your code be run and tested?

Other information

shashank40 commented 1 week ago

Hi @abrichr. I have added all the required updates to run OpenAdapt with necessary screenshots from my local.

Will be waiting for your review.

Also i found a lot of code issues while running OpenAdapt locally. There were many errors in code which needed to be fixed to run it locally. Some of these bugs were introduced last week.

Should i create a new issue and raise a PR?

abrichr commented 1 week ago

@shashank40 thank you! Please do 🙏

abrichr commented 1 week ago

Upon review it appears that you simply copied the screenshots from the README.

From the Issue Description:

screenshots of the new dashboard + system tray GUI functionality.

This involves:

going through the download + install + record + replay process, documenting the steps as you go (taking screenshots).

shashank40 commented 1 week ago

No @abrichr The only 4 screenshots taken from README are the feature images. Rest 11 images are screenshots from my mac.

Also there is a reason for feature images to be picked from README as there is not much difference from current photos.

But i will update those 4 with new ones

shashank40 commented 1 week ago

@abrichr Now i have added a detailed user guide separately as well. The documentation will now have developer guide and user guide separately.

shashank40 commented 1 week ago

Hey @abrichr would like to get an update on this documentation as well.

According to me this is now complete for both Users and Developers

abrichr commented 1 week ago

Hi @shashank40 , thank you for your patience. I am in touch with Gitbook support in order to enable previews on pull requests from forks. Will get back to you ASAP.

abrichr commented 2 days ago

Hi @shashank40 , here is an excerpt from an email thread with Gitbook support:

If I click on "Details" on either of the checks:

I see this revision:

If I click on the link to https://github.com/OpenAdaptAI/OpenAdapt/blob/docs/getting-started/welcome-to-openadapt/user-guide.md, I see a 404:

--

It seems that the files that are being referenced here are also being created in this PR. Which means that they are not yet referenced in the SUMMARY.md file for your docs.

The SUMMARY.md file is the source of truth for your docs, it's the file we use to build the table of contents for your documentation. Since it doesn't have a reference for those two files user-guide.md and developer-guide.md it goes to GitHub and GitHub returns a not found, since the file doesn't exist in the repo yet, it's still in the PR.

So for the link to work, the files have to be added to the SUMMARY.md file in the same PR. That way we'll create a revision where the links will be functional.

@shashank40 I would love to review this but in its current state I am unable to. Can you please make sure this works on Gitbook? I believe you should be able to click through the preview links.

shashank40 commented 2 days ago

@abrichr can i have the permission to create preview links on my PR? I cannot debug it without that.

Also the docs branch doesn't have this new code yet so you wont be able to test it on docs branch.

abrichr commented 1 day ago

@shashank40 I don't believe you need any special permissions.

Click "Show all checks":

Then click on "Details" to view the content live on gitbook.io.

Also the docs branch doesn't have this new code yet so you wont be able to test it on docs branch.

I'm just clicking on the "Details" link like I described above.

abrichr commented 1 day ago

From Gitbook support:

It seems that the files that are being referenced here are also being created in this PR. Which means that they are not yet referenced in the SUMMARY.md file for your docs.

The SUMMARY.md file is the source of truth for your docs, it's the file we use to build the table of contents for your documentation. Since it doesn't have a reference for those two files user-guide.md and developer-guide.md it goes to GitHub and GitHub returns a not found, since the file doesn't exist in the repo yet, it's still in the PR.

So for the link to work, the files have to be added to the SUMMARY.md file in the same PR. That way we'll create a revision where the links will be functional.

shashank40 commented 1 day ago

Yess now i can see the gitbook link. Thanks, Will add it

OpenAdaptAI / OpenAdapt

Update: Gitbook user guide. Issue #764 #771