Change docs structure v3.0 (#3722)

.github/vale/styles/Viam/AvoidWithSubstitutionViam.yml

@@ -7,7 +7,6 @@ action:
   name: replace
 swap:
   in the website: on the website
-  web app: Viam app or Viam platform
   user of an org: member of an org
   compute parts: Computer
   microprocessor: Raspberry Pi or Jetson or another specific term

.github/workflows/check_python_methods.py

@@ -235,7 +235,7 @@ def parse(type, names):
         # Parse the Docs site's service page
         if args.local:
             if type == "app" or type == "robot":
-                with open(f"dist/appendix/apis/{service}/index.html") as fp:
+                with open(f"dist/dev/reference/apis/{service}/index.html") as fp:
                     soup2 = BeautifulSoup(fp, 'html.parser')
             else:
                 if service in services_page_mapping.keys():

.github/workflows/docs.yml

@@ -47,23 +47,17 @@ jobs:
           name: tutorials-file
           path: ./public/tutorials/typesense.json
 
-      - name: Upload how-tos search file
-        uses: actions/upload-artifact@v4
-        with:
-          name: howtos-file
-          path: ./public/how-tos/typesense.json
-
       - name: Upload components models file
         uses: actions/upload-artifact@v4
         with:
           name: components-models-file
-          path: ./public/components/typesense.json
+          path: ./public/operate/reference/components/typesense.json
 
-      - name: Upload services models file
-        uses: actions/upload-artifact@v4
-        with:
-          name: services-models-file
-          path: ./public/services/typesense.json
+      # - name: Upload services models file
+      #   uses: actions/upload-artifact@v4
+      #   with:
+      #     name: services-models-file
+      #     path: ./public/operate/reference/services/typesense.json
 
   deploy:
     environment:
@@ -113,11 +107,6 @@ jobs:
         with:
           python-version: "3.9"
           cache: "pip" # caching pip dependencies
-      - name: Download the how-tos file
-        uses: actions/download-artifact@v4
-        with:
-          name: howtos-file
-          path: "how-tos"
       - name: Download the tutorials file
         uses: actions/download-artifact@v4
         with:
@@ -145,11 +134,11 @@ jobs:
         with:
           name: components-models-file
           path: "components"
-      - name: Download the services models file
-        uses: actions/download-artifact@v4
-        with:
-          name: services-models-file
-          path: "services"
+      # - name: Download the services models file
+      #   uses: actions/download-artifact@v4
+      #   with:
+      #     name: services-models-file
+      #     path: "services"
       - run: pip install -r .github/workflows/requirements.txt
       - name: "Update modular resources"
         run: python3 .github/workflows/get_modular_resources.py

.github/workflows/get_modular_resources.py

@@ -101,19 +101,19 @@ async def main():
             print("INSERTED")
             print(insert_resp)
 
-    # Get built-in resources from services/typesense.json
-    with open('services/typesense.json') as f:
-        resources = json.load(f)
-        for r in resources:
-            print("RESOURCE")
-            print(r)
-            r["last_updated"] = time_now
-            r["total_organization_usage"] = int(r["total_organization_usage"])
-            r["total_robot_usage"] = int(r["total_robot_usage"])
-            print(r)
-            insert_resp = typesense_client.collections['resources'].documents.upsert(r)
-            print("INSERTED")
-            print(insert_resp)
+    # # Get built-in resources from services/typesense.json
+    # with open('services/typesense.json') as f:
+    #     resources = json.load(f)
+    #     for r in resources:
+    #         print("RESOURCE")
+    #         print(r)
+    #         r["last_updated"] = time_now
+    #         r["total_organization_usage"] = int(r["total_organization_usage"])
+    #         r["total_robot_usage"] = int(r["total_robot_usage"])
+    #         print(r)
+    #         insert_resp = typesense_client.collections['resources'].documents.upsert(r)
+    #         print("INSERTED")
+    #         print(insert_resp)
 
     # Create a request to list registry items and get the response from the app
     request = ListRegistryItemsRequest(organization_id=cloud._organization_id)

.github/workflows/update_sdk_methods.py

@@ -435,10 +435,10 @@
     "SLAM service": "/services/slam/",
     "frame": "/services/frame-system/",
     "Viam app": "https://app.viam.com/",
-    "organization settings page": "/cloud/organizations/",
-    "image tags": "/fleet/dataset/#image-tags",
+    "organization settings page": "/manage/reference/organize/",
+    "image tags": "/data-ai/ai/create-dataset/#label-your-images",
     "API key": "/fleet/cli/#authenticate",
-    "board model": "/components/board/#configuration"
+    "board model": "/dev/reference/apis/components/board/"
 }
 
 ## Language-specific resource name overrides:
@@ -617,7 +617,7 @@ def link_data_types(sdk, data_type_string):
 
 ## Link matching text, used in write_markdown():
 ## NOTE: Currently does not support formatting for link titles
-## (EXAMPLE: bolded DATA tab here: https://docs.viam.com/appendix/apis/data-client/#binarydatabyfilter)
+## (EXAMPLE: bolded DATA tab here: https://docs.viam.com/dev/reference/apis/data-client/#binarydatabyfilter)
 def link_description(format_type, full_description, link_text, link_url):
 
     ## Supports 'md' link styling or 'html' link styling.
@@ -1830,23 +1830,23 @@ def write_markdown(type, names, methods):
                         if type == 'component':
                             ## Replace underscores, and convert generic_component to just generic:
                             resource_adjusted = resource.replace('generic_component', 'generic').replace('_','-')
-                            proto_anchor_link = '/appendix/apis/components/' + resource_adjusted + '/#' + proto_link
+                            proto_anchor_link = '/dev/reference/apis/components/' + resource_adjusted + '/#' + proto_link
                         elif type == 'service' and resource in ['base_remote_control', 'motion', 'navigation', 'slam', 'vision']:
-                            proto_anchor_link = '/appendix/apis/services/' + resource.replace('base_remote_control', 'base-rc') + '/#' + proto_link
+                            proto_anchor_link = '/dev/reference/apis/services/' + resource.replace('base_remote_control', 'base-rc') + '/#' + proto_link
                         elif type == 'service' and resource == 'data_manager':
-                            proto_anchor_link = '/appendix/apis/services/data/#' + proto_link
+                            proto_anchor_link = '/dev/reference/apis/services/data/#' + proto_link
                         elif type == 'service' and resource == 'generic_service':
-                            proto_anchor_link = '/appendix/apis/services/generic/#' + proto_link
+                            proto_anchor_link = '/dev/reference/apis/services/generic/#' + proto_link
                         elif type == 'service' and resource == 'mlmodel':
-                            proto_anchor_link = '/appendix/apis/services/ml/#' + proto_link
+                            proto_anchor_link = '/dev/reference/apis/services/ml/#' + proto_link
                         elif type == 'app' and resource == 'app':
-                            proto_anchor_link = '/appendix/apis/fleet/#' + proto_link
+                            proto_anchor_link = '/dev/reference/apis/fleet/#' + proto_link
                         elif type == 'app' and resource in ["billing", "mltraining"]:
-                            proto_anchor_link = '/appendix/apis/' + resource.replace('mltraining','ml-training') + '-client/#' + proto_link
+                            proto_anchor_link = '/dev/reference/apis/' + resource.replace('mltraining','ml-training') + '-client/#' + proto_link
                         elif type == 'app' and resource in ["data", "dataset", "data_sync"]:
-                            proto_anchor_link = '/appendix/apis/data-client/#' + proto_link
+                            proto_anchor_link = '/dev/reference/apis/data-client/#' + proto_link
                         elif type == 'robot':
-                            proto_anchor_link = '/appendix/apis/' + resource + '/#' + proto_link
+                            proto_anchor_link = '/dev/reference/apis/' + resource + '/#' + proto_link
 
                         ## Fetch just the first sentence from the proto_override_file (first text string terminated by '.\n'), ignoring hugo
                         ## shortcodes like alerts ('{{%.*%}}.*{{% \[a-b].* %}}'), which precede some override files' (proto descriptions')

.github/workflows/upload_tutorials.py

@@ -31,19 +31,6 @@ async def main():
             print("INSERTED")
             print(insert_resp)
 
-    # Get how-tos from how-tos/typesense.json
-    with open('how-tos/typesense.json') as f:
-        resources = json.load(f)
-        for r in resources:
-            print("RESOURCE")
-            r["date"] = int(r["date"])
-            print(r)
-            r["last_updated"] = time_now
-            print(r)
-            insert_resp = typesense_client.collections['tutorials'].documents.upsert(r)
-            print("INSERTED")
-            print(insert_resp)
-
     # Deleting documents that didn't get updated (presumably deleted)
     try:
         res = typesense_client.collections['tutorials'].documents.delete({'filter_by': 'last_updated: <' + str(time_now)})

assets/js/howtos.js

@@ -98,9 +98,9 @@ let refinementLists = [customRefinementList({
   items: [
     { label: "Data Management", value: "data" },
     { label: "Machine Learning", value: "ml" },
-    { label: "Core", value: "core" },
+    { label: "Control hardware", value: "core" },
     { label: "Fleet Management", value: "fleet" },
-    { label: "Registry", value: "registry" },
+    { label: "Integrate other hardware", value: "registry" },
     { label: "Mobility", value: "mobility" },
   ],
 }),

assets/js/index.js

@@ -4,6 +4,7 @@ var siteMenuSubmenus = document.getElementsByClassName(
 );
 
 function submenuToggle(menu, toggle) {
+    console.log(menu)
     let open = false;
     if (toggle.children[0].className === "fas fa-chevron-right") {
         open = true;
@@ -17,16 +18,29 @@ function submenuToggle(menu, toggle) {
     }
 
     // add or remove collapse class to children
-    let immediateChildren = menu.querySelector("ul").children;
+    let menuChildren = menu.querySelector("span>ul").children;
     if (open) {
-        for (let c of immediateChildren) {
+        for (let c of menuChildren) {
             c.classList.remove("collapse");
         }
     } else {
-        for (let c of immediateChildren) {
+        for (let c of menuChildren) {
             c.classList.add("collapse");
         }
     }
+    let pageChildren = menu.querySelector("span>div>ul").children;
+    if (pageChildren) {
+        if (open) {
+            for (let c of pageChildren) {
+                c.classList.remove("collapse");
+            }
+        } else {
+            for (let c of pageChildren) {
+                c.classList.add("collapse");
+            }
+        }
+    }
+
 }
 
 for (let menu of siteMenuSubmenus) {

assets/js/tutorials.js

@@ -77,8 +77,6 @@ const customRefinementList = instantsearch.connectors.connectRefinementList(
       </ul>
       <ul class="pill-explainer">
       <li><p><strong>tutorial</strong>: Projects that show you how to use different parts of Viam.</p></li>
-      <li><p><strong>how-to</strong>: Step-by-step guides to complete tasks.</p></li>
-      <li><p><strong>quickstart</strong>: <5 min step-by-step guide to complete tasks.</p></li>
       <li><p><strong>blogpost</strong>: Sample projects you can build.</p></li>
       <li><p><strong>codelab</strong>: Community projects and example project.</p></li>
       </ul>
@@ -215,8 +213,6 @@ search.addWidgets([
     sortBy: ["name:asc"],
     items: [
       { label: "tutorial" },
-      { label: "how-to" },
-      { label: "quickstart" },
       { label: "blogpost" },
       { label: "codelab" },
     ],

assets/scss/_sidebar-tree.scss

@@ -6,6 +6,7 @@
     margin-right: -15px;
     margin-left: -15px;
     font-size: 1rem;
+    font-weight: 300;
 
     @include media-breakpoint-up(md) {
         @supports (position: sticky) {
@@ -63,7 +64,7 @@
     a, .emptynode {
         display: inline-block;
         padding-bottom: 0.375rem;
-        color: black;
+        color: #333333;
         text-decoration: none;
 
         &:hover {
@@ -96,6 +97,7 @@
 
     li i { // Layout of icons
         padding-right: 0.5em;
+        -webkit-text-stroke: 1px whitesmoke;
         &:before{
             display: inline-block;
             text-align: center;
@@ -112,7 +114,7 @@
 
 .td-sidebar {
     @include media-breakpoint-up(md) {
-        padding-top: 4rem;
+        padding-top: 6rem;
         background-color: $td-sidebar-bg-color;
         padding-right: 1rem;
         border-right: 1px solid $td-sidebar-border-color;
@@ -170,4 +172,15 @@
 li .indent {
     font-size: 0.833rem;
     padding-left: 0.75rem;
+}
+
+@media (min-width: 768px) {
+    .header-only > span > span.emptynode:hover {
+    color: #aaa;
+    }
+
+    .ul-2 > li:not(:last-child) {
+        padding-bottom: 8px;
+        border-bottom: 1px solid #ccc;
+    }
 }