Major guides page revamp

[PepperTheVixen]

I have completely reworked the guides page and added additional guides in order to bring it up to speed with SVA 1.5+ and to improve the guides. This includes updated farm building construction and tips for using the map interface when constructing a building. The guides page is now also available in the compiled docs and relevant links have been updated in the other docs pages to point to the updated guides page. Future docs compilations with kramdown will now include the guides page.

[PepperTheVixen]

e98702d adds a guide for using all current features of the object tracker. Keybinds.md and config.md have yet to be updated with the necessary info. I plan on making these updates in a separate PR

[khanshoaib3]

@PepperTheVixen Can you please change the path to guides.md from local to the one pointing to the github repo. I explained in the review above why it'll cause an issue.

[PepperTheVixen]

@khanshoaib3 I'm confused. I don't see a review anywhere? Not sure if my screen reader is skipping over an element or something

[khanshoaib3]

@PepperTheVixen Oh, and I don't see any share link thingy. Well, here's what I said earlier,

Changing the guides page link to a local one will cause problem because I've excluded compiling the guides.md file in the ruby script. My thinking was that since guides may get updated at a different pace than the releases resulting in the local compiled guides.html not being up to date.

[ParadoxiKat]

I also can't find any way to read or even see that a review was requested. How frustrating github! How can we make the development docs branch point to the development guide if it's not a local reference though? Could we just run the docs update more frequently if guides needs to be updated more frequently?

[PepperTheVixen]

What about pointing the md link to the guides page on the master branch, leaving the guides.md in the Ruby script, and adding a line to the beginning of the guide saying to check the local compiled docs for the most up-to-date guides docs? Currently the guide on the master is outdated with the latest release that players are using.

[khanshoaib3]

Could we just run the docs update more frequently if guides needs to be updated more frequently?

But the thing is, the docs are also provided to the user with the release builds, which can't be updated as frequently as the one on github. This is good for the installation instructions and such but not for guides IMO.

[khanshoaib3]

leaving the guides.md in the Ruby script, and adding a line to the beginning of the guide saying to check the local compiled docs for the most up-to-date guides docs?

I like the idea but wouldn't the github docs be the latest? Once the docs are merged into master branch (or development if we reference that)

[khanshoaib3]

Should we maybe have a separate docs website? Like the one Shockah has for project fluent? ref

[ParadoxiKat]

@khanshoaib3 Yes; we can use the darkade.games setup for it. Now that stardew-access 1.6 is stable-ish I can spend this weekend mostly focused on getting that all setup. Server maintenance is a high priority need for me this weekend regardless. I think it would be best if we could have a more official website presence with the official 1.6 release. Doesn't have to start out pretty. I'll get server updates started now.

[ParadoxiKat]

Thing is in the future we might have beta builds ahead of a stable master. So regardless which we pick someone will get redirected to a wrong version of guides. Example, if we set guides to point to the live url for development -- then a user on the stable master branch, browsing locally, can get redirected to the online version of development guides. Same in reverse if we leave it pointing to master -- beta users browsing local docs will end up redirected to online master guides. In either case, an offline user browsing local docs would get redirected to an online page for guides rather than the local copy. I wonder if there is a way to leave it with the live url, pointed to the master branch on master docs and development on development docs... but also change it to a local reference inside the zip file the user will download. That way they can browse it fully offline / always stick with docs current to their running version.

[PepperTheVixen]

@khanshoaib3 @ParadoxiKat What if we include a local HTML copy of the guides page and add a section at the top which says what SDA build that version of the guides file is intended for as well as a link to the live MD version? That would give offline players access to guides, provide a way to find the most up-to-date guides page on the repo, avoid setting up GitHub actions, and avoid reverting to a link to the guide on the master branch which is currently out of date with the build players are using? Alternatively, we could change the link to dev instead of master for the time being.

[ParadoxiKat]

So we keep the local file references but just add a link on the local guides page to the live page. I like this idea; seems clean and straight forward. Though I have minimal familiarity with the documentation system so @khanshoaib3 will need to ultimately decide.

[PepperTheVixen]

1f9ca66 maintains the local guides.html and adds links to the live docs. Beta and release. This way it's available even if a player has no internet connection and they also have a link to the live docs so those can be viewed with an internet connection to get the most up-to-date documentation.

Would it be possible to get the Ruby compiler script to update the release version whenever it's run? Say it gets the version from the manifest json? I don't know anywhere near enough Ruby to do this myself

[khanshoaib3]

I like the idea. And until we have the docs system on darkade.games set up, we can have it like this.

Would it be possible to get the Ruby compiler script to update the release version whenever it's run? Say it gets the version from the manifest json?

It should be possible, it'll be simple string search and replace thing. Wait, this will include fetching the manifest.json from the master branch. This task is more suitable as a bash script or something.

I do want to have a github workflow set up that builds the mod and uploads it onto nexus and github. When I do that, I'll also remove the compiler script and have it included directly in the workflow and thats when I guess I could update the release tags in guides.md more effectively.

For now though, the script needs to be updated to not exclude the guides.md, I'll do that and merge the PR.

Thanks for the new guides Pepper :heart: