DVP-357: Algokit CLI Overview (import, +reference, +feature pages)

.gitmodules

@@ -13,3 +13,6 @@
 [submodule "imports/repos/py-algorand-sdk"]
 	path = imports/repos/py-algorand-sdk
 	url = https://github.com/algorand/py-algorand-sdk
+[submodule "imports/repos/algokit-cli"]
+	path = imports/repos/algokit-cli
+	url = https://github.com/algorandfoundation/algokit-cli

astro.config.mjs

@@ -392,40 +392,132 @@ export default defineConfig({
               collapsed: false,
               items: [
                 {
-                  label: 'Project Tools',
-                  link: 'reference/algokit-cli/project-tools',
+                  label: 'Overview',
+                  link: 'reference/algokit-cli/overview',
+                },
+                {
+                  label: 'Compile',
+                  link: 'reference/algokit-cli/compile',
                 },
                 {
-                  label: 'Configuration',
+                  label: 'Completions',
+                  link: 'reference/algokit-cli/completions',
+                },
+                {
+                  label: 'Config',
                   link: 'reference/algokit-cli/config',
                 },
                 {
-                  label: 'App Compilation',
-                  link: 'reference/algokit-cli/compilation',
+                  label: 'TestNet Dispenser',
+                  link: 'reference/algokit-cli/dispenser',
+                },
+                {
+                  label: 'Doctor',
+                  link: 'reference/algokit-cli/doctor',
                 },
                 {
-                  label: 'Client Generation',
-                  link: 'reference/algokit-cli/client-generation',
+                  label: 'Explore',
+                  link: 'reference/algokit-cli/explore',
                 },
                 {
-                  label: 'Testnet Funding',
-                  link: 'reference/algokit-cli/testnet-funding',
+                  label: 'Generate',
+                  link: 'reference/algokit-cli/generate',
                 },
                 {
-                  label: 'Explorer',
-                  link: 'reference/algokit-cli/explorer',
+                  label: 'Goal',
+                  link: 'reference/algokit-cli/goal',
                 },
                 {
-                  label: 'Node Operations',
-                  link: 'reference/algokit-cli/node-ops',
+                  label: 'Init',
+                  link: 'reference/algokit-cli/init',
+                },
+                {
+                  label: 'Localnet',
+                  link: 'reference/algokit-cli/localnet',
+                },
+                {
+                  label: 'Project',
+                  collapsed: false,
+                  items: [
+                    {
+                      label: 'Overview',
+                      link: 'reference/algokit-cli/project/overview',
+                    },
+                    {
+                      label: 'Bootstrap',
+                      link: 'reference/algokit-cli/project/bootstrap',
+                    },
+                    {
+                      label: 'Deploy',
+                      link: 'reference/algokit-cli/project/deploy',
+                    },
+                    {
+                      label: 'Link',
+                      link: 'reference/algokit-cli/project/link',
+                    },
+                    {
+                      label: 'List',
+                      link: 'reference/algokit-cli/project/list',
+                    },
+                    {
+                      label: 'Run',
+                      link: 'reference/algokit-cli/project/run',
+                    },
+                  ],
                 },
                 {
                   label: 'Tasks',
-                  link: 'reference/algokit-cli/tasks',
+                  collapsed: false,
+                  items: [
+                    {
+                      label: 'Overview',
+                      link: 'reference/algokit-cli/tasks/overview',
+                    },
+                    {
+                      label: 'Analyze',
+                      link: 'reference/algokit-cli/tasks/analyze',
+                    },
+                    {
+                      label: 'IPFS',
+                      link: 'reference/algokit-cli/tasks/ipfs',
+                    },
+                    {
+                      label: 'Mint',
+                      link: 'reference/algokit-cli/tasks/mint',
+                    },
+                    {
+                      label: 'NFD Lookup',
+                      link: 'reference/algokit-cli/tasks/nfd',
+                    },
+                    {
+                      label: 'Asset opt-(in|out)',
+                      link: 'reference/algokit-cli/tasks/opt',
+                    },
+                    {
+                      label: 'Send',
+                      link: 'reference/algokit-cli/tasks/send',
+                    },
+                    {
+                      label: 'Sign',
+                      link: 'reference/algokit-cli/tasks/sign',
+                    },
+                    {
+                      label: 'Transfer',
+                      link: 'reference/algokit-cli/tasks/transfer',
+                    },
+                    {
+                      label: 'Vanity Adress',
+                      link: 'reference/algokit-cli/tasks/vanity-adress',
+                    },
+                    {
+                      label: 'Wallet',
+                      link: 'reference/algokit-cli/tasks/wallet',
+                    },
+                  ],
                 },
                 {
-                  label: 'CLI Reference',
-                  link: 'reference/algokit-cli/reference',
+                    label: 'Algokit CLI Reference',
+                    link: 'reference/algokit-cli/cli-reference',
                 },
               ],
             },

imports/build/python/Makefile

@@ -28,4 +28,4 @@ utils: clean
 	export SPHINX_REPO=utils && \
 	$(FULL_SPHINX_COMMAND) && \
 	cp -r _build/starlight/apidocs/* "../../../src/content/docs/reference/algokit-utils-py/API Reference"
-
+	

imports/build/python/conf.py

@@ -48,8 +48,7 @@
             "auto_mode": True,
         },
     ]
-
-
+
 else:
     raise ValueError(
         f"Invalid repo: {repo}. Make sure to set the SPHINX_REPO environment variable."

imports/scripts/algokit-cli.ts

@@ -0,0 +1,176 @@
+import { readFile, writeFile, readdir, mkdir, rm, cp, mkdtemp } from 'fs/promises';
+import path from 'path';
+
+type FileTransformer = (content: string) => string;
+
+interface DirectoryTransformation {
+    src: string;
+    transformations: FileTransformer[];
+    dest: string;
+}
+
+interface FileTransformation {
+    src: string;
+    transformations: FileTransformer[];
+    dest: string;
+}
+
+const convertH1ToFrontmatter: FileTransformer = (content: string) => {
+    const h1Match = content.match(/^#\s+(.+)$/m);
+    if (!h1Match) return content;
+
+    const title = h1Match[1].trim();
+    const newContent = content.replace(/^#\s+.+$/m, '').trim();
+
+    return `---
+title: ${title}
+---
+
+${newContent}`;
+};
+
+const correctTypo: FileTransformer = (content: string): string => {
+    return content
+        .replaceAll('immedately', 'immediately')
+        .replaceAll('lastest', 'latest')
+        .replaceAll('directy', 'directly');
+}
+
+
+const stripLinkExtensions: FileTransformer = (content: string): string => {
+    return content.replaceAll('.md', '');
+};
+const changeFeatureLinks: FileTransformer = (content: string): string => {
+    return content.replaceAll('/features', '');
+};
+
+const changeReferenceLinks: FileTransformer = (content: string): string => {
+    return content.replaceAll(/\.\.?\/cli\/index/g, 'cli-reference');
+};
+
+const removeLine = (line: string): FileTransformer => {
+    return (content: string): string => {
+        return content.replaceAll(line, '');
+    }
+};
+
+const removeToc: FileTransformer = (content: string): string => {
+    return content.replaceAll(/^ *- \[.+$/gm, '');
+}
+
+async function getAllFiles(directory: string, filePattern: string): Promise<string[]> {
+    const files: string[] = [];
+
+    async function scan(dir: string) {
+        const entries = await readdir(dir, { withFileTypes: true });
+
+        for (const entry of entries) {
+            const fullPath = path.join(dir, entry.name);
+
+            if (entry.isDirectory()) {
+                await scan(fullPath);
+            } else if (entry.isFile() && entry.name.match(filePattern)) {
+                files.push(fullPath);
+            }
+        }
+    }
+
+    await scan(directory);
+    return files;
+}
+
+async function processDirectories(configs: DirectoryTransformation[]) {
+    try {
+        for (const config of configs) {
+            const tempDir = await mkdtemp('.tmp');
+
+            await cp(config.src, tempDir, { recursive: true });
+            const files = await getAllFiles(tempDir, '\\.md$');
+
+            for (const file of files) {
+                const content = await readFile(file, 'utf-8');
+                const transformedContent = config.transformations.reduce(
+                    (currentContent, transform) => transform(currentContent),
+                    content
+                );
+                await writeFile(file, transformedContent, 'utf-8');
+            }
+
+            await rm(config.dest, { recursive: true, force: true });
+            await mkdir(config.dest, { recursive: true });
+            await cp(tempDir, config.dest, { recursive: true });
+            await rm(tempDir, { recursive: true, force: true });
+
+            console.log(`Successfully processed files from ${config.src} to ${config.dest}`);
+        }
+    } catch (error) {
+        console.error('Error processing files:', error);
+    }
+}
+
+async function processFile(configs: FileTransformation[]) {
+    try {
+        for (const config of configs) {
+            const content = await readFile(config.src, 'utf-8');
+            const transformedContent = config.transformations.reduce(
+                (currentContent, transform) => transform(currentContent),
+                content
+            );
+
+            await mkdir(path.dirname(config.dest), { recursive: true });
+            await writeFile(config.dest, transformedContent, 'utf-8');
+
+            console.log(`Successfully processed file from ${config.src} to ${config.dest}`);
+        }
+    } catch (error) {
+        console.error('Error processing file:', error);
+    }
+}
+
+await processDirectories([
+    {
+        src: './../repos/algokit-cli/docs/features',
+        transformations: [
+            convertH1ToFrontmatter,
+            stripLinkExtensions,
+            changeFeatureLinks,
+            changeReferenceLinks,
+            correctTypo,
+            removeLine('> For details on executing `algokit localnet` without `docker` or `podman` refer to the [codespaces](#codespaces) section.')
+        ],
+        dest: './../../src/content/docs/reference/algokit-cli'
+    },
+]);
+await processFile([
+    {
+        src: './../repos/algokit-cli/docs/cli/index.md',
+        transformations: [
+            convertH1ToFrontmatter,
+            stripLinkExtensions,
+            changeFeatureLinks,
+            changeReferenceLinks,
+            removeToc,
+        ],
+        dest: './../../src/content/docs/reference/algokit-cli/cli-reference.md'
+    },
+    {
+        src: './../repos/algokit-cli/docs/algokit.md',
+        transformations: [
+            convertH1ToFrontmatter,
+            stripLinkExtensions,
+            changeFeatureLinks,
+            changeReferenceLinks,
+        ],
+        dest: './../../src/content/docs/reference/algokit-cli/overview.md'
+    },
+    {
+        src: './../../src/content/docs/reference/algokit-cli/project.md',
+        transformations: [],
+        dest: './../../src/content/docs/reference/algokit-cli/project/overview.md'
+    },
+    {
+        src: './../../src/content/docs/reference/algokit-cli/tasks.md',
+        transformations: [],
+        dest: './../../src/content/docs/reference/algokit-cli/tasks/overview.md'
+    },
+]);