Merge pull request #3107 from balena-io/vipulgupta2048/version-python

Create versioned docs for Python SDK

.cspell/balena-words.txt

@@ -7,7 +7,6 @@ balena-builder
 balenacli
 balenahup
 balenalib
-balenasdk
 balenista
 balenistas
 Barys
@@ -29,8 +28,10 @@ metalsmith
 model
 multicontainer
 Nicky
+nodesdk
 openbalena
 private-contracts
+pythonsdk
 resinio
 Rulemotion
 SBVR

.gitignore

@@ -15,7 +15,7 @@ tmp
 
 # Ignore external docs that are pulled via tools/fetch-external.sh
 # pages/reference/sdk/node-sdk.md
-pages/reference/sdk/python-sdk.md
+# pages/reference/sdk/python-sdk.md
 
 pages/reference/supervisor/supervisor-api.md
 pages/reference/supervisor/upgrade-policy.md
@@ -47,9 +47,13 @@ config/dictionaries/balenacli.json
 shared/balena-cli-versions/
 
 # Ignore dynamic balena-SDK version docs
-config/dictionaries/balenasdk.json
+config/dictionaries/nodesdk.json
 shared/balena-sdk-versions/
 
+# Ignore dynamic Python SDK version docs
+config/dictionaries/pythonsdk.json
+shared/balena-sdk-python-versions/
+
 # Ignore dynamic assets generated for Getting Started
 static/img/device/**
 config/dictionaries/device.json

config/navigation.txt

@@ -151,8 +151,8 @@ Reference
 
   CLI[/reference/balena-cli/$balenacli]
   SDKs
-    Node.js SDK[/reference/sdk/node-sdk/$balenasdk]
-    Python SDK[/reference/sdk/python-sdk]
+    Node.js SDK[/reference/sdk/node-sdk/$nodesdk]
+    Python SDK[/reference/sdk/python-sdk/$pythonsdk]
     Deprecation Policy[/reference/sdk/deprecation-policy]
 
   Diagnostics

config/redirects.txt

@@ -196,8 +196,8 @@
 /tools/cli /reference/balena-cli/latest/
 /tools/sdk/ /reference/sdk/node-sdk/latest/
 /tools/sdk /reference/sdk/node-sdk/latest/
-/tools/python-sdk/ /reference/sdk/python-sdk/
-/tools/python-sdk /reference/sdk/python-sdk/
+/tools/python-sdk/ /reference/sdk/python-sdk/latest/
+/tools/python-sdk /reference/sdk/python-sdk/latest/
 /runtime/resin-base-images/ /reference/base-images/balena-base-images/
 /runtime/resin-base-images /reference/base-images/balena-base-images/
 /configuration/custom-docker-base-images/ /reference/base-images/customer-docker-base-images/
@@ -274,6 +274,10 @@
 /reference/sdk/node-sdk/ /reference/sdk/node-sdk/latest/
 /reference/sdk/node-sdk /reference/sdk/node-sdk/latest/
 
+# Versioned Python.js SDK docs
+/reference/sdk/python-sdk/ /reference/sdk/python-sdk/latest/
+/reference/sdk/python-sdk /reference/sdk/python-sdk/latest/
+
 # Important: keep dynamic redirect below the static redirects
 # https://developers.cloudflare.com/pages/platform/redirects/
 

pages/reference/sdk/node-sdk.md

@@ -4,11 +4,11 @@ title: balena Node.js SDK Documentation
 layout: balena-sdk.html
 
 dynamic:
-  variables: [ $balenasdk ]
-  ref: $original_ref/$balenasdk
-  $switch_text: balena SDK version $balenasdk
+  variables: [ $nodesdk ]
+  ref: $original_ref/$nodesdk
+  $switch_text: balena SDK version $nodesdk
 ---
 
-# Balena Node.js SDK {{ $balenasdk.version }} Documentation
+# Balena Node.js SDK {{ $nodesdk.version }} Documentation
 
 {{import "balena-sdk-versions"}}

pages/reference/sdk/python-sdk.md

@@ -0,0 +1,14 @@
+---
+title: balena Python SDK Documentation
+
+layout: balena-sdk-python.html
+
+dynamic:
+  variables: [ $pythonsdk ]
+  ref: $original_ref/$pythonsdk
+  $switch_text: balena SDK version $pythonsdk
+---
+
+# Balena Python SDK {{ $pythonsdk.version }} Documentation
+
+{{import "balena-sdk-python-versions"}}

templates/balena-sdk-python.html

@@ -0,0 +1,8 @@
+{% extends "default.html" %}
+
+{% block dynamicSwitchCustom %}
+<p class="dynamic-switch__append">
+</p>
+{% endblock %}
+
+<div id="output"></div>

tools/build.sh

@@ -16,6 +16,9 @@ node ./tools/versioning.js https://github.com/balena-io/balena-cli/blob/master/d
 # Generate versioned balena-sdk docs
 node ./tools/versioning.js https://github.com/balena-io/balena-sdk/blob/master/DOCUMENTATION.md
 
+# Generate versioned balena-python-sdk docs
+node ./tools/versioning.js https://github.com/balena-io/balena-sdk-python/blob/master/DOCUMENTATION.md
+
 # Generate Masterclasses Dynamically
 ./tools/build-masterclass.sh
 

tools/fetch-external.sh

@@ -100,7 +100,7 @@ cd shared/sdk/ && {
 } &
 
 # get latest python SDK docs
-curl --fail --show-error -o pages/reference/sdk/python-sdk.md -L https://github.com/balena-io/balena-sdk-python/raw/master/DOCUMENTATION.md &
+# curl --fail --show-error -o pages/reference/sdk/python-sdk.md -L https://github.com/balena-io/balena-sdk-python/raw/master/DOCUMENTATION.md &
 
 # get latest base images ref docs
 cd pages/reference/base-images/ && {

tools/versioning.js

@@ -251,9 +251,20 @@ async function main() {
     process.exit(1);
   }
 
+  const versionsConfigFileTemplate = {
+    "balenasdk": "nodesdk",
+    "balenasdkpython": "pythonsdk",
+  }
+
   // Parse repository details
   const { owner, name: repoName, filepath } = parseGithubUrl(repoUrl);
-  const versionsConfigFile = `./config/dictionaries/${repoName.replaceAll(/-/g, "")}.json`
+
+  // Create versioned config file - Doxx doesn't allow dashes in the config file name
+  const versionsFileName = repoName.replaceAll(/-/g, "")
+  // Doxx treats config files with common names as same, so balenasdk and balenasdkpython config files needs to be named differently
+  const versionsConfigFile = versionsConfigFileTemplate[versionsFileName] ? versionsConfigFileTemplate[versionsFileName] : versionsFileName
+  const versionsConfigFilePath = `./config/dictionaries/${versionsConfigFile}.json`
+
   const versionedDocsFolder = path.join(__dirname, `../shared/${repoName}-versions`)
 
   console.log(`Started versioning ${repoName} docs`)
@@ -263,7 +274,7 @@ async function main() {
     const tagVersions = await fetchGitHubTags(owner, repoName);
 
     // Write versions configuration
-    await fsPromises.writeFile(versionsConfigFile, JSON.stringify(tagVersions, null, 2));
+    await fsPromises.writeFile(versionsConfigFilePath, JSON.stringify(tagVersions, null, 2));
     if (fs.existsSync(versionedDocsFolder)) {
       await fsPromises.rm(versionedDocsFolder, { recursive: true });
     }