search

TalonCommunity / Wiki

Community maintained wiki for Talon Voice
https://talon.wiki
80 stars 80 forks source link

Wiki Refactor #250

Closed C-Loftus closed 5 months ago

C-Loftus commented 6 months ago

@splondike @2shea

I believe the refactor of the wiki should be done. https://talon-wiki-refactor.netlify.app/

This merge adds

  1. a refactor to use docusaurus instead of jekyll
  2. better grouping of the unofficial docs
  3. better styling and theming
  4. a community logo
  5. better grouping of the navbar with a quickstart tab
  6. various small fixes of old broken links or irrelevant content
  7. a markdown autoformatter and better dev process with pre-commit

I believe this is ready to merge unless you have comments. I cannot add the algolia search integration until the site is deployed to a stable public URL.

I have not changed any of the content in the wiki itself besides for significant errors (overly verbose runons spanning multiple lines, outdated info, etc.) I think it makes sense to merge and then slowly add to the new main based on user feedback instead of doing both a content, organization, and style refactor all at once. I think user feedback is very important.

Let me know what you think

netlify[bot] commented 6 months ago

Deploy Preview for talon-wiki-refactor ready!

Name Link
Latest commit f51ed8c04d55297c30af9d8014ae0d349601292b
Latest deploy log https://app.netlify.com/sites/talon-wiki-refactor/deploys/66130fcb12e95e0008ccf60b
Deploy Preview https://deploy-preview-250--talon-wiki-refactor.netlify.app
Preview on mobile
Toggle QR Code...

QR Code

Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify site configuration.

splondike commented 6 months ago

Thanks for all the work, it's looking good! A few comments below:

2shea commented 6 months ago

I believe this is ready to merge unless you have comments. I cannot add the algolia search integration until the site is deployed to a stable public URL.

My recommendation for the migration is to:

  1. Point DNS of https://talon.wiki to new netlify app which is currently built from staging branch and deploys to https://talon-wiki-refactor.netlify.app/.
  2. After DNS points to the new site and it is confirmed to be working, merge a PR into main with the changes in staging branch, adjust configuration in netlify from jeklyll -> docusaurus.
  3. After main branch is successfully building new site, point DNS of https://talon.wiki back to old netlify app https://talonwiki.netlify.app/ which is built from main branch.

To be clear, I'm recommending NOT to merge this to main while DNS points to the current netlify app or there will be down time of the wiki. Also, we should keep staging and main separate and merge from a different branch so that we do not break the staging build in netlify. Doing the migration using the steps above avoids down time and also makes it easier to flip DNS back to the old one if anything goes wrong. We also can still visit the old site using the netlify domain.

I can flip DNS to the new site anytime. Would just need to know when we are satisfied with the new site.

Thoughts?

2shea commented 6 months ago

The splitting up of the unofficial docs page makes sense however the navigation layout loses some of the structure I was trying to put into that page. I like how you've combined the two 'overview' type sections into the 'Talon API Overview' page, but as an entrypoint to a large number of the rest of the pages it kind of gets lost in the current positioning. I might suggest you make it a top level page called 'Talon API' and then move all the other pages that used to be on the same page beneath it in a tree structure. Hopefully that would direct people new to the system to read it first.

Colton and I spoke over the weekend, and at the time, the sidebar looked like this:

image

In this layout (above), the 'Python API Documentation' did not not have any content iirc, but it was just an organizing structure for the pages inside of it. My concern was the pages in there felt a bit hidden and required extra clicks to discover them. I wasn't convinced at the time that nesting those pages was helping with organization since that was the only section nested, and I suggested flattening. Looking at the old site (below), though, i realize now how the structure has diverged significantly from the original intent, and some of the organization and flow of the pages may have been lost.

image

@splondike are you suggesting a structure that looks more like this?

Basic Customization
.talon Files
.talon-list Files
key() action
Talon API Overview and Concepts
> Modules
> Contexts
> Actions
> Lists
> Captures
> Tags
> Apps 
> Modes
> Scopes
> Settings
Tips and Tricks
Advanced Scripting Features

The content is still split across multiple pages and the two 'overview' pages remain merged, but the ordering of the Talon Concepts matches the original wiki and they are nested under a type of 'landing page'. The key() action feels a bit out of place, but open to suggestions including leaving it there and figuring out a better placement later.

C-Loftus commented 6 months ago

I can flip DNS to the new site anytime. Would just need to know when we are satisfied with the new site.

Looks good with me Emily. Please do what you think is best, just since I am less familiar with the hosting and DNS side. I am not sure if it makes a big deal, whatever is easiest.

re: Nesting

With regards to nesting, I personally don't think the unofficial talon docs benefits from it. I thought so at first, but there really isn't a hierarchy to the pages, although I agree there is a rough order. The challenge with talon is that the python and the talonscript side are so mixed that putting the "API" in its own folder is a bit confusing, since the "API" page also contains things relevant to simpler customization (i.e. the built in settings)

Some things eventually should be nested, but I don't think right now it makes sense. (i.e. eventually it would make sense to document other actions and put them all in an actions folder along with key() but right now we only have one.

One thing I will say is that it is super tedious to change all the markdown links for nesting so it makes sense to align on this 100% before moving this around more

re: setttings

Moved that into the desired page.

2shea commented 6 months ago

One thing I will say is that it is super tedious to change all the markdown links for nesting so it makes sense to align on this 100% before moving this around more

Thank you for doing the tedious work you have done already. It's much appreciated. I also support aligning on further changes before doing more edits. Good call, and thank you for bringing it up. 👍

C-Loftus commented 6 months ago

Only other thing I am potentially thinking of with nesting is breaking is up into python-side and talon-side folders (names of these folders would be tweaked and not verbatim). (i.e. there would be a modules and contexts file under the python-side folder but there wouldn't need to be that file under the talon-side folder since that is an exclusively Python-side concept. However, for settings there would be a file for talon-side/settings and a python-side/settings.

This would make it much easier for newer users who just want to start writing scripts using only talon files and also make each page less verbose. I think a lot of people get confused at the start of customizing Talon, since you don't need to know anything about creating modules/contexts/lists etc to actually write basic talon scripts.

Downside for this is that it would require a lot of verbal restructuring and for some things it does make sense to group together. I don't think there is necessary one 100% right way to do this in the current format

splondike commented 6 months ago

I think my favourite structure would look something like this:

Basic customization
Talon framework - Name instead of Talon API Overview
    .talon Files
    .talon-list Files
    Modules and Contexts
    Actions
    Apps
    Lists and Captures - I'd merge Advanced Scripting Features in with lists. Captures could probably be its own section since lists would get pretty long.
    Modes
    Scopes
    Settings
    Tags
Talon library reference - This would be where details about all the modules talon provides, e.g. skia (canvas), file system watcher, clipboard, imgui, window management etc. We'd move the API functions section from tips and tricks into this top level page.
    key() action
Tips and tricks

Basic customization was intended to give people who just wanted to make simple changes something easier to digest. It only deals with .talon files since aegis designed them to be accessible to less technical folks. So I've put that first. If people wanted to dive deeper, the overview sections were intended to be read first so you could understand how everything fit together before getting into the details.

I've made a distinction between the 'Talon framework' and 'library reference' above. As with programming in other systems a framework is something you have to write your code to fit in to and a library is a set of functionality you can call out to as needed (I agree with these definitions). In our case I think the framework should stay reasonably stable whereas we might gain and lose libraries over time (e.g. we used to have text to speech and now don't).

I'm not against having a flat list of pages, but personally like a bit of hierarchy to hopefully make the structure more apparent. If we did want it flat I'd suggest something like this. Mainly just having the overview second from the top.

Basic customization
Talon framework overview
.talon Files
.talon-list Files
Modules and Contexts
Actions
Apps
Lists and Captures
Modes
Scopes
Settings
Tags
Advanced Scripting Features
key() action
Tips and tricks
C-Loftus commented 6 months ago

Ok, that generally makes sense and I think that is reasonable. I still think that splitting up things between talon-side and python-side might be useful at some point since many users may never touch Python. But maybe given how tightly coupled things are, that would be a leaky abstraction. Once this is merged, in future PRs I may start to clean things up / reduce verbosity. Right now there is a lot of great information, but it is in a lot of big paragraphs that I am afraid people frankly will probably not read. (i.e. using more small pages, with more bullet points, visual callouts, and cross-page linking)

re: Basic customization was intended to give people who just wanted to make simple changes something easier to digest. It should be at the start

Yup I agree, and don't I also have it at the start of the page folder right now as you do? Wasn't sure if you are getting at something else.

re: captures

Yup, I am fine splitting that into its own page

re: naming

Yup that is fair to me. I also like we have a spot for key action that makes sense longer term and provides a place where others can create other similar pages.

re: alignment

@2shea can you confirm that the aforementioned structure seems good? I think it is honestly pretty similar to the previous nested structure before flattening, so wasn't sure if you'd like it. I think this is a fine compromise with me.

2shea commented 6 months ago

The nested structure proposed by @splondike looks good to me! 👍

I'm also fine with the flattened, but I agree that the nesting in that format provides some organization that the flattened version is lacking.

C-Loftus commented 6 months ago

The nested structure proposed by @splondike looks good to me! 👍

I'm also fine with the flattened, but I agree that the nesting in that format provides some organization that the flattened version is lacking.

Great, I will iterate on this when I get a chance and then it should be ready for formal review before merging. Shouldn't be too much to change. I agree and think that nesting is a better longer term solution

2shea commented 6 months ago

Great, I will iterate on this when I get a chance and then it should be ready for formal review before merging. Shouldn't be too much to change. I agree and think that nesting is a better longer term solution

Ok, great. Once the changes are in and we are happy with them, let me know and I can switch DNS to the new site. This is a reminder that DNS should be updated before we can merge with main.

C-Loftus commented 6 months ago

Responded to feedback and pushed everything to this PR branch. Added a few small cleanup things and continued to trim or add content conservatively if something was glaringly wrong.

@splondike @2shea I think this is ready for review. Emily, as i have thought of it more I think I would prefer to merge this in such a way that it gets merged into main rather than switching DNS. I don't think that downtime is really a significant issue, And the issue is that if it isn't on the main branch it is a bit confusing for people who want to make contributions

I plan to ask people for contributions regarding the basic usage section. right now that is very sparse but it is quite easy to fill in just with tables of essential commands.

2shea commented 6 months ago

Emily, as i have thought of it more I think I would prefer to merge this in such a way that it gets merged into main rather than switching DNS. I don't think that downtime is really a significant issue, And the issue is that if it isn't on the main branch it is a bit confusing for people who want to make contributions

Merging to main without updating the config in netlify will break the site. I am currently the only one with access to the netlify config (adding more users costs $$). Please do not merge to main without coordinating with me. I would prefer to make the config changes in netlify in a way that doesn't need to coordinate that change with the merging with main, and keeps the old site in a working state just in case. Doing this migration by updating DNS allows that to happen more smoothly on my end and also with no down time for users of the site. I hear that you don't see downtime as much of an issue, but IMO there's no reason to have downtime if it's not necessary. There is an easy workaround.

Deploying the site from another branch other than main would be temporary. We would point DNS to the new site built off of the branch with your docusaurus refactor, then point DNS back to the site built off of main once the changes have been merged and netlify settings are reconfigured to be compatible with docusaurus. The end state is that the new site will be deployed from main branch. I agree that it's expected for contributors to work off of main branch and that this is the ideal end state.

If helpful, I'm happy to jump on a call/zoom to discuss if that'd be helpful.

C-Loftus commented 6 months ago

Ok sure that is fair, whatever is best. I am aligned with that then. And yes, I will never merge anything like this to main without prior review from you both.

splondike commented 6 months ago

Looks good to me now, thanks!

2shea commented 6 months ago

Excellent. I'm occupied this evening, but I will do the migration tomorrow.

C-Loftus commented 6 months ago

Cool, thanks both! I have switched this to a draft PR until the refactor is stable after a while on the talon.wiki deployment and we are all happy with it.

2shea commented 6 months ago

A few more things before I do the migration:

  1. I'm going to push a commit to add a link to the old site from the announcement bar. It will look like this:

    Untitled

  2. I'm going to set up redirects in Netlify so that links to the old site don't 404. These are the links from the old site:

    ~/TalonCommunity/Wiki main* 6s ❯ curl https://talon.wiki/sitemap.xml | grep loc | sed 's/<[^>]*>//g'                                                           16:37:36
% Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                             Dload  Upload   Total   Spent    Left  Speed
100  1544  100  1544    0     0   5813      0 --:--:-- --:--:-- --:--:--  5938
https://talon.wiki/blog/
https://talon.wiki/key_action/
https://talon.wiki/CODE_OF_CONDUCT/
https://talon.wiki/CONTRIBUTING/
https://talon.wiki/FAQ/
https://talon.wiki/Running-Linux-or-Mac-Talon-Using-Windows-Dragon/
https://talon.wiki/basic_customization/
https://talon.wiki/basic_usage/
https://talon.wiki/beta_talon/
https://talon.wiki/getting_started/
https://talon.wiki/hardware/
https://talon.wiki/improving_recognition_accuracy/
https://talon.wiki/
https://talon.wiki/other_integrations/
https://talon.wiki/speech_engines/
https://talon.wiki/talon_related_resources/
https://talon.wiki/talon_user_file_sets/
https://talon.wiki/tobii_4c_tips/
https://talon.wiki/tobii_5/
https://talon.wiki/troubleshooting/
https://talon.wiki/unofficial_talon_docs/

Curling them on the new site, most of them 404:

~/TalonCommunity/Wiki main* ❯ while read url; do  echo "Checking $url... " && curl -so /dev/null -w "%{http_code}" "$url" && echo ""; done <check_site_urls    16:36:42
Checking https://new.talon.wiki/blog/...
404
Checking https://new.talon.wiki/key_action/...
404
Checking https://new.talon.wiki/CODE_OF_CONDUCT/...
404
Checking https://new.talon.wiki/CONTRIBUTING/...
404
Checking https://new.talon.wiki/FAQ/...
404
Checking https://new.talon.wiki/Running-Linux-or-Mac-Talon-Using-Windows-Dragon/...
404
Checking https://new.talon.wiki/basic_customization/...
404
Checking https://new.talon.wiki/basic_usage/...
404
Checking https://new.talon.wiki/beta_talon/...
404
Checking https://new.talon.wiki/getting_started/...
404
Checking https://new.talon.wiki/hardware/...
404
Checking https://new.talon.wiki/improving_recognition_accuracy/...
404
Checking https://new.talon.wiki/...
200
Checking https://new.talon.wiki/other_integrations/...
404
Checking https://new.talon.wiki/speech_engines/...
404
Checking https://new.talon.wiki/talon_related_resources/...
404
Checking https://new.talon.wiki/talon_user_file_sets/...
404
Checking https://new.talon.wiki/tobii_4c_tips/...
404
Checking https://new.talon.wiki/tobii_5/...
404
Checking https://new.talon.wiki/troubleshooting/...
404
Checking https://new.talon.wiki/unofficial_talon_docs/...
200

I think most of them are due to the paths changing, e.g., /basic_customization/ is now /Customization/basic_customization/. I will work on setting up redirects so we don't break links to the site. I may not get to changing DNS today, though I hope to get to it in the next couple days.

  1. I noticed the favicon is still using the talon logo instead of the talon wiki logo. @C-Loftus any idea why that is happening? Untitled copy
C-Loftus commented 6 months ago

re: redirect and announcement bar link

Both of those seem like good ideas, thank you for doing that. No rush at all, appreciate you doing this.

re: logo

Have you tried clearing cache? I do not have that favicon/logo in either chrome or firefox on Linux.

image

2shea commented 6 months ago

The redirect rules appear to be working 👍 Here's the results curling the old site urls after the redirect rules were applied:

~/TalonCommunity/Wiki staging* 9s ❯ while read url; do echo "Checking $url... " && curl -L -so /dev/null -w "%{http_code}" "$url" && echo ""; done <check_site_urls
Checking https://new.talon.wiki/blog/...
200
Checking https://new.talon.wiki/key_action/...
200
Checking https://new.talon.wiki/CODE_OF_CONDUCT/...
200
Checking https://new.talon.wiki/CONTRIBUTING/...
200
Checking https://new.talon.wiki/FAQ/...
200
Checking https://new.talon.wiki/Running-Linux-or-Mac-Talon-Using-Windows-Dragon/...
200
Checking https://new.talon.wiki/basic_customization/...
200
Checking https://new.talon.wiki/basic_usage/...
200
Checking https://new.talon.wiki/beta_talon/...
200
Checking https://new.talon.wiki/getting_started/...
200
Checking https://new.talon.wiki/hardware/...
200
Checking https://new.talon.wiki/improving_recognition_accuracy/...
200
Checking https://new.talon.wiki/...
200
Checking https://new.talon.wiki/other_integrations/...
200
Checking https://new.talon.wiki/speech_engines/...
200
Checking https://new.talon.wiki/talon_related_resources/...
200
Checking https://new.talon.wiki/talon_user_file_sets/...
200
Checking https://new.talon.wiki/tobii_4c_tips/...
200
Checking https://new.talon.wiki/tobii_5/...
200
Checking https://new.talon.wiki/troubleshooting/...
200
Checking https://new.talon.wiki/unofficial_talon_docs/...
200
2shea commented 6 months ago

Have you tried clearing cache? I do not have that favicon/logo in either chrome or firefox on Linux.

I tried in a private window and also clearing the cache. Still showing as the talon logo for me in safari. Chrome looks good.

C-Loftus commented 6 months ago

Have you tried clearing cache? I do not have that favicon/logo in either chrome or firefox on Linux.

I tried in a private window and also clearing the cache. Still showing as the talon logo for me in safari. Chrome looks good.

I don't know the specifics, but favicons are cached differently and longer than other web assets. I had this issue previously but it went away when I removed the favicon cache in firefox (imagine there must be something similar for safari). Almost positive this isn't an issue on our end/docusaurus

https://stackoverflow.com/questions/37997070/why-are-favicons-cached-longer https://discussions.apple.com/thread/250501971?sortBy=best

2shea commented 6 months ago

Hi! @C-Loftus, would you mind splitting out the two latest commits that have content changes into a separate branch?

https://github.com/TalonCommunity/Wiki/pull/250/commits/f445b9769d21dd8e3b728fe731aea4bee45361ba https://github.com/TalonCommunity/Wiki/pull/250/commits/127af5892f2882989d266225565eaa3acb7cc86d

I'm seeing some changes in there I want to comment on, but I don't want any back and forth to delay doing the migration to Docusaurus. I'd like to do that migration today.

2shea commented 6 months ago

Reverting the two content changes isn't trivial because they happen amidst other formatting/minor changes. This PR is pretty large already, so ideally we'd separate out content changes. However, reviewing the content changes as part of this PR may be the quickest path forward at this point. So, let's do that.

Let's aim to only do minor edits from here until after we do the migration. Additional content edits should be PR'd against main once we have made the switch. That way content edits will be easier to review.

2shea commented 6 months ago

Looks good as of f51ed8c. Let's hold off on further changes until this get merged into main.

DNS for https://talon.wiki now points to the new netlify app built of docusaurus built off of this branch. It should be visible in ~5min once the ttl expires.

C-Loftus commented 6 months ago

Awesome thank you for your work on this Emily! Yes, will not touch this beyond addressing requested edits.

On Mon, Apr 8, 2024 at 8:28 PM Emily Shea @.***> wrote:

Looks good as of f51ed8c https://github.com/TalonCommunity/Wiki/pull/250/commits/f51ed8c04d55297c30af9d8014ae0d349601292b. Let's hold off on further changes until this get merged into main.

DNS for https://talon.wiki now points to the new netlify app built of docusaurus built off of this branch. It should be visible in ~5min once the ttl expires.

— Reply to this email directly, view it on GitHub https://github.com/TalonCommunity/Wiki/pull/250#issuecomment-2043930219, or unsubscribe https://github.com/notifications/unsubscribe-auth/AQ2T6ZZINAU6YGKS4T6KKNTY4MY2LAVCNFSM6AAAAABFGG6QT6VHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDANBTHEZTAMRRHE . You are receiving this because you were mentioned.Message ID: @.***>

2shea commented 5 months ago

I've switched netlify config to temporarily deploy from branches other than staging and main to make this safe to merge. The branches are main-migration which is a copy of staging and deploys to the apex talon.wiki and main-jekyll-legacy which is a copy of main and deploys to old.talon.wiki.

2shea commented 5 months ago

This should now be safe to merge. After merge, I will update netlify config and point back to main.