DOCUMENTATION: Better npm run doc, plus minor folder reorganization (#693)

package.json

@@ -1,7 +1,7 @@
 {
   "name": "bitburner",
   "license": "SEE LICENSE IN license.txt",
-  "version": "2.4.0dev",
+  "version": "2.4.1dev",
   "main": "electron-main.js",
   "author": {
     "name": "Daniel Xie, Olivier Gagnon, et al."
@@ -108,7 +108,7 @@
     "url": "git+https://github.com/bitburner-official/bitburner-src.git"
   },
   "scripts": {
-    "doc": "npx api-extractor run && npx api-documenter markdown && rm input/bitburner.api.json && rm -r input && git add markdown/ && git add tsdoc-metadata.json",
+    "doc": "bash ./tools/doc.sh",
     "format": "prettier -c --write .",
     "format:report": "prettier -c .",
     "start": "cd .app && http-server -p 8000",
@@ -127,7 +127,6 @@
     "preversion": "npm install && npm run test",
     "version": "sh ./tools/build-release.sh && git add --all",
     "postversion": "git push -u origin dev && git push --tags",
-    "changelog": "node tools/fetch-changelog/index.js --from=$(cat last_changelog_hash) > changelog.md",
-    "bundle-doc": "node tools/bundle-doc/index.js"
+    "changelog": "node tools/fetch-changelog/index.js --from=$(cat last_changelog_hash) > changelog.md"
   }
 }

src/Documentation/ui/DocumentationRoot.tsx

@@ -3,32 +3,21 @@ import React from "react";
 import Button from "@mui/material/Button";
 import { MD } from "../../ui/MD/MD";
 
-import { getPage } from "./root";
+import { getPage } from "../root";
 import { Navigator, useHistory } from "../../ui/React/Documentation";
 import { CONSTANTS } from "../../Constants";
-
-const resolveRelativePath = (folder: string, relative: string): string => {
-  const noLastSlash = folder.endsWith("/") ? folder.slice(0, folder.length - 1) : folder;
-  const lastIndex = noLastSlash.lastIndexOf("/");
-  const prefix = lastIndex === -1 ? "" : noLastSlash.slice(0, lastIndex + 1);
-  const suffix = relative.slice("../".length);
-  return prefix + suffix;
-};
-
-const resolvePath = (currentPath: string, newPath: string): string => {
-  const lastIndex = currentPath.lastIndexOf("/");
-  const folder = lastIndex === -1 ? "" : currentPath.slice(0, lastIndex + 1);
-  if (!newPath.startsWith("../")) return folder + newPath;
-
-  return resolveRelativePath(folder, newPath);
-};
+import { resolveFilePath } from "../../Paths/FilePath";
 
 export function DocumentationRoot(): React.ReactElement {
   const history = useHistory();
   const page = getPage(history.page);
   const navigator = {
     navigate(relPath: string, external: boolean) {
-      const newPath = resolvePath(history.page, relPath);
+      const newPath = resolveFilePath("./" + relPath, history.page);
+      if (!newPath) {
+        console.error(`Bad path ${relPath} from ${history.page} while navigating docs.`);
+        return;
+      }
       if (external) {
         const ver = CONSTANTS.isDevBranch ? "dev" : "stable";
         const url = `https://github.com/bitburner-official/bitburner-src/blob/${ver}/src/Documentation/ui/doc/${newPath}`;

src/ui/React/Documentation.tsx

@@ -1,4 +1,5 @@
 import React, { useContext, useState } from "react";
+import { FilePath, asFilePath } from "../../Paths/FilePath";
 
 interface Navigator {
   navigate: (s: string, external: boolean) => void;
@@ -9,17 +10,17 @@ export const Navigator = React.createContext<Navigator>({ navigate: () => undefi
 export const useNavigator = (): Navigator => useContext(Navigator);
 
 interface History {
-  pages: string[];
-  page: string;
-  push(p: string): void;
+  pages: FilePath[];
+  page: FilePath;
+  push(p: FilePath): void;
   pop(): void;
   home(): void;
 }
 
-const defaultPage = "index.md";
+const defaultPage = asFilePath("index.md");
 
 const HistoryContext = React.createContext<History>({
-  page: "",
+  page: defaultPage,
   pages: [],
   push: () => undefined,
   pop: () => undefined,
@@ -29,7 +30,7 @@ const HistoryContext = React.createContext<History>({
 export const Provider = HistoryContext.Provider;
 export const useHistory = (): History => useContext(HistoryContext);
 
-const onPush = (h: History, p: string): History => {
+const onPush = (h: History, p: FilePath): History => {
   return {
     ...h,
     page: p,
@@ -57,7 +58,7 @@ export const HistoryProvider = (props: React.PropsWithChildren<object>): React.R
   const [history, setHistory] = useState<History>({
     page: defaultPage,
     pages: [],
-    push(p: string) {
+    push(p: FilePath) {
       setHistory((h) => onPush(h, p));
     },
     pop() {

tools/bundle-doc/index.js

@@ -1,7 +1,7 @@
 const fs = require("fs");
 
 const files = [];
-const docRoot = "./src/Documentation/ui/doc";
+const docRoot = "./src/Documentation/doc";
 const processDir = (dir) => {
   console.log(dir);
   for (const file of fs.readdirSync(dir)) {

tools/doc.sh

@@ -0,0 +1,21 @@
+#!/bin/bash
+
+echo "Bundling ingame documentation..."
+node tools/bundle-doc/index.js
+
+echo ""
+echo "Using API Extractor to generate mappings for Netscript API definitions..."
+npx api-extractor run
+
+echo ""
+echo "Creating markdown from Netscript API mappings..."
+npx api-documenter markdown
+
+echo ""
+echo "Running cleanup tasks..."
+rm input/bitburner.api.json && rm -r input
+
+# This git add is needed due to documenter using wrong line endings. Console spam discarded.
+git add markdown/ 2> /dev/null && git add tsdoc-metadata.json 2> /dev/null
+echo ""
+echo "Documentation build completed."