Feat: Adding documentation (#31)

* docs: Added Blank pages and first mockup of a Quick Start Guide
* Fixed problems with previous iteration
* Fleshed out QuickStart checklist content (and temporarily disabled check)
* added links to credits
* Added code generated changelog
* improved visuals
* Cleaned up empty card display
* Made docs card into its own component
* Extended changelog generation with branch & master tags
* Renamed Doc pages
* Added content and improved look of various parts
* Fixed git permissions error
* Fixed codegen to work wihout master
* Bumped version to 0.11.0
* Removed sudo passwoed field

.mise.toml

@@ -18,7 +18,7 @@ outputs = ['build/bin/backend']
 [tasks."build:frontend"]
 description = 'Build the Frontend'
 run = "node --no-warnings=ExperimentalWarning 'util/build.mjs' -q -o frontend"
-sources = ['package.json', 'lib/package.json', '{src,lib}/**/*.*']
+sources = ['package.json', 'lib/package.json', '{src,lib,docs}/**/*.*']
 outputs = ['dist/index.js']
 
 [tasks."build:collect"]

backend/version

@@ -1 +1 @@
-0.10.12
+0.11.0

build.sh

@@ -1,3 +1,2 @@
 #!/bin/bash
 exec node "--no-warnings=ExperimentalWarning" "util/build.mjs" "$@"
-

docs/ChangeLog.mdx

@@ -0,0 +1,8 @@
+import { ChangeLog } from "./components/ChangeLog";
+import changelog from './codegen/changelog.codegen';
+
+# Check out what the latest updates are
+
+<ChangeLog tags={changelog}/>
+
+

docs/Credits.mdx

@@ -1,9 +1,9 @@
 # Credits
 
-Massive shout outs to:
+I, [@CEbbinghaus](https://github.com/CEbbinghaus) am merely the creator & maintainer of [MicroSDeck](https://github.con/CEbbinghaus/MicroSDeck), All the real credit goes to 
 
-- [@jeiza]()
-- [@rainbyte]()
+- [@jeiza](https://github.com/jessebofill)
+- [@rainybyte](https://github.com/jfreuden)
 - [@nabelo]()
 
-without whom this plugin just simply wouldn't exist as it does today.
+without whom this plugin just simply wouldn't exist as it does today.

docs/MicroSD%20Cards.mdx

@@ -0,0 +1,19 @@
+# Micro SD Cards
+
+The main purpose of this plugin is to help organize MicroSD cards for the Steamdeck. As such the cards themselves are the biggest aspect of MicroSDeck.
+
+All the management of steam games happens via the Steam UI, MicroSDeck just tracks all changes to the games saved on the MicroSD card to display when they are not currently plugged in.
+Not only are you able to view all games on each MicroSD card that has been inserted but it also displays which MicroSD card(s) a particular game is installed on.
+As such the identification of MicroSD cards is a crucial part of effectively using MicroSDeck to its fullest. MicroSDeck lets you name each card with full emoji support to best uniquely identify it, and hint at what it contains.
+And the name is a just text, any number of naming schemes can be used. As long as you are able to tell them apart the sky is the limit.
+
+Some examples of naming schemes are:
+- Using the vendor name (e.g Sandisk, Samsung, ADATA)
+- Using small stickers or pens to mark the cards
+- Using numbered or lettered cases to identify the cards
+
+But you can get as creative as you want. As long as you know which physical card belongs to which digital name.
+
+## Registering a Card
+
+To Register a MicroSD card with MicroSDeck it simply has to be formatted by Steam and inserted. To Format the MicroSD card navigate into the Settings menu and click Format under `System > SystemSettings > Format SD Card`. It can take some time to format the MicroSD Card. Be patient. If it still doesn't work, try unplugging and replugging the MicroSD card **After** Steam has finished formatting it.

docs/Non-Steam%20Games.mdx

@@ -0,0 +1,13 @@
+# Non Steam Games
+
+MicroSDeck supports adding Non-Steam games to MicroSD Cardds. This is to support emulation since it is possible to install ROM's onto the MicroSD card. Although the functionality of adding Non-Steam games is not limited to just emulation. Any "game" that steam lists can be added to the MicroSD card.
+
+Adding a Non-Steam "game" to the MicroSD card is as easy as opening the MicroSDeck plugin and clicking on the "..." button for the MicroSD card you want to add the game to.
+
+//TODO: Insert image
+
+Under the Non-Steam Games tab you will find checkboxes to specify which games should be considered "installed" on the MicroSD card.
+
+//TODO: Insert image
+
+Afer hitting Save you will see the game in the list of games on the card. It will also show the card name on the game

docs/codegen/changelog.codegen

@@ -0,0 +1,66 @@
+
+const { execSync } = require('child_process');
+const commitLog = execSync('git log --pretty="%H %aN %aE %s"').toString().trim();
+const tagLog = execSync('git log --tags --no-walk --pretty="%H %S"').toString().trim();
+
+const headCommit = execSync('git rev-parse HEAD').toString().trim();
+
+let additionalTags = [];
+
+let masterCommit = null;
+try {
+	masterCommit = execSync('git rev-parse master').toString().trim();
+} catch (_) { }
+
+if (masterCommit) {
+	const masterVersion = execSync('git show master:backend/version').toString().trim();
+	additionalTags = [
+		[masterCommit, `master @ ${masterCommit.substring(0, 7)} (${masterVersion})`],
+		...additionalTags
+	];
+}
+
+// This is not built on latest master so we are gonna display info on this branch
+if (additionalTags.length == 0 || masterCommit !== headCommit) {
+	const branchName = execSync("git rev-parse --abbrev-ref HEAD").toString().trim();
+	additionalTags = [
+		[headCommit, `${branchName} @ ${headCommit.substring(0, 7)} (Pre-Release)`],
+		...additionalTags
+	];
+}
+
+const tagArray = [
+	...additionalTags,
+	...tagLog.split('\n').map(line => {
+		const [hash, tag] = line.split(' ');
+		return [hash, tag];
+	})
+]
+
+const tags = Object.fromEntries(tagArray);
+
+const commits = commitLog.split('\n').map(line => {
+	const [hash, author, email, ...message] = line.split(' ');
+	return { hash, author, email, message: message.join(' ') };
+});
+
+const taggedCommits = [];
+
+for (let i = 0; i < commits.length;) {
+	let taggedCommit = { tag: tags[commits[i].hash], commits: [] };
+
+	do {
+		taggedCommit.commits.push(commits[i]);
+	}
+	while (++i < commits.length && !tags[commits[i].hash]);
+
+	taggedCommits.push(taggedCommit);
+}
+
+
+module.exports = function () {
+	return `
+//@ts-nocheck
+export default ${JSON.stringify(taggedCommits)};
+	`;
+};

docs/codegen/version.codegen

@@ -0,0 +1,12 @@
+
+const { readFileSync } = require('fs');
+const { join } = require('path');
+
+const version = readFileSync(join(__dirname, '../../version'), { encoding: "utf8" }).trim();
+
+module.exports = function () {
+	return `
+//@ts-nocheck
+export default ${JSON.stringify(version)};
+	`;
+};

docs/components/ChangeLog.tsx

@@ -0,0 +1,39 @@
+import { ReactElement } from "react";
+import React from "react";
+import { Logger } from "../../src/Logging";
+
+function TagWithCommits({ tag, commits }: { tag: string, commits: Commit[] }): ReactElement {
+	if (commits.length == 0) {
+		Logger.Warn("Tag {tag} did not contain any commits. Skipping", { tag: JSON.stringify(tag) });
+		return (<></>);
+	}
+
+	if (!tag) {
+		Logger.Warn("Tag is not defined. Skipping", { tag: JSON.stringify(tag) });
+		return (<></>);
+	}
+
+	return (
+		<div style={{ margin: "6px auto" }}>
+			<h3 style={{ fontWeight: "bolder" }}>{tag}</h3>
+			<ul>
+				{
+				//TODO: categorize them based on semantic commit
+					commits.map(v => (
+						<li>
+							{v.message}
+						</li>
+					))
+				}
+			</ul>
+		</div>
+	)
+}
+
+export function ChangeLog({ tags }: React.PropsWithChildren<{ tags: TaggedCommits[] }>): ReactElement {
+	return (
+		<>
+			{tags.map(({ tag, commits }) => <TagWithCommits tag={tag} commits={commits} />)}
+		</>
+	)
+}

docs/components/QuickStart/CheckList.tsx

@@ -0,0 +1,32 @@
+import React, { ReactElement } from "react";
+import { FaCheckCircle, FaQuestionCircle } from "react-icons/fa";
+import { useMicroSDeckContext, CardsAndGames } from "../../../lib/src";
+
+type CheckListItem = {
+	check: (cardsAndGames: CardsAndGames) => boolean,
+	body: any
+}
+
+export function CheckListItem({ title, children, check }: React.PropsWithChildren<{ title: string, check: (cardsAndGames: CardsAndGames) => boolean }>): ReactElement {
+	const { cardsAndGames } = useMicroSDeckContext();
+
+	const is_completed = /* Math.random() < 0.5 && */ check(cardsAndGames);
+
+	return (
+		<>
+			<div style={{display: "flex", flexDirection: "row"}}>
+				<div style={{ marginTop: "1.6em", marginRight: "12px" }}>{is_completed ? <FaCheckCircle style={{ color: "#7df47d" }} size={26} /> : <FaQuestionCircle style={{ color: "#7dbcf4" }} size={26} />}</div>
+				<h2 style={{marginBottom: "0px"}}>{title}</h2>
+			</div>
+			{is_completed ? <></> : children}
+		</>
+	);
+}
+
+export function CheckList({ children }: React.PropsWithChildren<{}>): ReactElement {
+	return (
+		<>
+			{children}
+		</>
+	);
+}

docs/index.mdx

@@ -1,9 +1,57 @@
+import { Navigation, SideMenu } from "@decky/ui";
 import { CurrentCard } from "./components/CurrentCard";
+import { CheckList, CheckListItem } from "./components/QuickStart/CheckList";
+import { FaPlug } from "react-icons/fa"
+import { FaGear } from "react-icons/fa6";
+import { IoGridSharp } from "react-icons/io5";
 
-# Hello, World!
+> ## Under Construction 🚧👷
+> The docs are still under construction. There will be incomplete, missing or inaccurate information for the time being
+
+
+# Quick Start
+
+Here is a little checklist you can use to get you started with MicroSDeck
+
+<CheckList>
+	<CheckListItem title="Registered a Card" check={(cardsAndGames) => cardsAndGames.length > 0}>
+		To Register a MicroSD card with MicroSDeck it simply has to be formatted by Steam and inserted.
+
+		To Format the MicroSD card navigate into the <FaGear/> <button onClick={() => Navigation.OpenMainMenu()}>Settings</button> menu and click Format under `System > SystemSettings > Format SD Card`.
+
+		> ℹ️ **Note:**
+		> It can take some time to format the MicroSD Card. Be patient.
+		> If it still doesn't work, try unplugging and replugging the MicroSD card **After** Steam has finished formatting it.
+
+	</CheckListItem>
+	<CheckListItem title="Installed a Game" check={(cardsAndGames) => cardsAndGames.filter(([_, games]) => games.length > 0).length > 0}>
+		Now that you have your MicroSD Card registered with MicroSDeck its time to install a game to it. 
+
+		For this simply Head on over to your <IoGridSharp/> <button onClick={() => Navigation.NavigateToLibraryTab()}>Library</button> and install any game. Make sure to install it to the MicroSD Card and not the Internal Drive.
+
+		MicroSDeck should automatically pick up on the game after it has finished installing. This can take a few seconds...
+	</CheckListItem>
+	<CheckListItem title="Named a Card" check={(cardsAndGames) => cardsAndGames.filter(([card]) => card.name != "").length > 0}>
+		Wonderful, Now that you have both Registered a MicroSD Card and Installed a game on it, it is now time to name the card. This aids in quickly finding the Card that you have installed the specified game to.
+
+		For this just open the <button onClick={() => Navigation.OpenSideMenu(SideMenu.QuickAccess)}>Quick Access</button> menu (the `...` button on the right hand side of the steamdeck) and navigate to the MicroSDeck Plugin by tabbing down to the <FaPlug/> Decky Plugins section. Under the plugin list you should find MicroSDeck.
+
+		There are listed the Cards that are registered with MicroSDeck. You can rename any of them by clicking the `...` button and hitting **Edit** in the popup. 
+
+		Giving your MicroSD card a meaningful name is half the battle. Try and come up with a system to easily label your cards. Some examples are:
+
+		* With many different MicroSD card vendors it might be possible to just use the vendor name (e.g Sandisk, Samsung, ADATA)
+		* Using small stickers (they have to be very thin) or Using pens, Little icons can be applied to the SD Cards (Emoji names are supported in MicroSDeck)
+		* Some MicroSD card cases are numbered or lettered allowing you identify the cards easily
+
+		But you can get as creative as you want. As long as you know which physical card belongs to which digital name.
+	</CheckListItem>
+	<CheckListItem title="Added Non Steam Game"check={(cardsAndGames) => cardsAndGames.filter(([_, games]) => games.filter(v => !v.is_steam).length > 0).length > 0}>
+		The last step is to add a Non-Steam Game. This is also achieved via the same popup menu as renaming a card.
+
+		Under the TextBox to set the card name there is a dropdown to allow toggling which Non-Steam Games should be considered "installed" on this card. 
+	</CheckListItem>
+</CheckList>
 
-This is the beginning of the docs, Unfortunately they are still under construction ⚠️🚧👷
 
-Here is a little demo of why my 20 hour investment into this doc engine was totally worth it:
 
-> <CurrentCard/>

package.json

@@ -14,7 +14,7 @@
 	"author": "Christopher-Robin <[email protected]>",
 	"license": "GPL-2.0",
 	"scripts": {
-		"prebuild": "exec node --no-warnings=ExperimentalWarning util/versioning.mjs update package.json lib/package.json",
+		"prebuild": "(node --no-warnings=ExperimentalWarning util/ci.mjs) && (node --no-warnings=ExperimentalWarning util/versioning.mjs update package.json lib/package.json)",
 		"build": "shx rm -rf dist && rollup -c",
 		"bundle": "shx rm -rf dist && rollup -c",
 		"watch": "rollup -c -w",