[CAT-815] Edit Docs (#123)

* filter out docs for internal implementations; move files to correct nesting structure * updating links, adding missing index files, making sure files have unique slugs * fix build script * add back test script * add updated pipeline yaml * don't try to nest csharp docs * only one level of nesting * lowercase links * updated harness pipeline yaml
IndicoDataSolutions · Nov 9, 2023 · 0096e22 · 0096e22
1 parent 1ed13b6
commit 0096e22
Show file tree

Hide file tree

Showing 11 changed files with 208 additions and 33 deletions.
diff --git a/docfx_project/docfx.json b/docfx_project/docfx.json
@@ -5,19 +5,14 @@
         {
           "src": "../",
           "files": [
-            "IndicoV2*/**.csproj"
-          ],
-          "exclude": [
-            "docfx_project/**",
-            "*Tests/**",
-            "IndicoV2.V1Adapters/**",
-            "IndicoV2.StrawberryShake/**"
+            "IndicoV2.Abstractions/**.csproj"
           ]
         }
       ],
       "dest": "apiV2",
       "disableGitFeatures": false,
-      "outputFormat": "markdown"
+      "outputFormat": "markdown",
+      "filter": "filterConfig.yml"
     }
   ]
 }
diff --git a/docfx_project/filterConfig.yml b/docfx_project/filterConfig.yml
@@ -0,0 +1,11 @@
+apiRules: 
+  - exclude:
+      uidRegex: IndicoV2\.Workflows\.Models\.Workflow
+  - exclude:
+      uidRegex: IndicoV2\.Submissions\.Models\.SubmissionSs
+  - exclude:
+      uidRegex: IndicoV2\.Submissions\.Models\.FilterConverter
+  - exclude:
+      uidRegex: IndicoV2\.Ocr\.Models\.ExtractionJobResult
+  - exclude:
+      uidRegex: IndicoV2\.CommonModels\.Pagination\.HasCursor
diff --git a/docs.Dockerfile b/docs.Dockerfile
diff --git a/harness-docs.yaml b/harness-docs.yaml
@@ -21,7 +21,7 @@ pipeline:
                     repo: harbor.devops.indico.io/indico/indico-client-csharp
                     tags:
                       - <+codebase.commitSha>
-                    dockerfile: docs.Dockerfile
+                    dockerfile: readme_docs/docs.Dockerfile
           platform:
             os: Linux
             arch: Amd64
@@ -45,7 +45,31 @@ pipeline:
                     image: harbor.devops.indico.io/indico/indico-client-csharp:<+codebase.commitSha>
                     command: |
                       cd /indico-client-csharp
-                      ./scripts/build_docs.sh
+                      chmod +x ./readme_docs/build_docs.sh
+                      ./readme_docs/build_docs.sh
+
+                      cp -r docfx_project/apiV2 $DOCS_PATH
+                      git clone https://user:[email protected]/IndicoDataSolutions/indico-readme.git
+                      cd indico-readme
+                      git config --global user.email "[email protected]"
+                      git config --global user.name "cat-automation"
+                      git checkout -b docs-version-$TAG
+
+                      mkdir -p markdown
+                      cp -r $DOCS_PATH ./markdown/$LANGUAGE
+                      bash add_frontmatter_yaml.sh
+
+                      git add ./markdown/$LANGUAGE
+                      git commit -m "a set of doc changes"
+
+                      git push --set-upstream origin docs-version-$TAG
+                      curl -L \
+                        -X POST \
+                        -H "Accept: application/vnd.github+json" \
+                        -H "Authorization: Bearer $GITHUB_TOKEN" \
+                        -H "X-GitHub-Api-Version: 2022-11-28" \
+                        https://api.github.com/repos/IndicoDataSolutions/indico-readme/pulls \
+                        -d '{"title":"Amazing new feature","body":"Please pull these awesome changes in!","head":"docs-version-'"$TAG"'","base":"main"}'
                     shell: Bash
                     infrastructure:
                       type: KubernetesDirect
@@ -71,9 +95,9 @@ pipeline:
                     envVariables:
                       GITHUB_TOKEN: <+secrets.getValue("readmeghpat")>
                       TAG: <+codebase.commitSha>
-                      LANGUAGE: chsarp
+                      LANGUAGE: c-sharp
                       README_API_KEY: <+secrets.getValue("meghanhickeyreadmepat")>
-                      DOCS_PATH: /harness/csharp
+                      DOCS_PATH: /harness/c-sharp
                   timeout: 1m 30s
         tags: {}
   properties:
@@ -83,4 +107,4 @@ pipeline:
         repoName: indico-client-csharp
         build: <+input>
   identifier: Generate_CSharp_Docs
-  name: Generate CSharp Docs
+  name: Generate CSharp Docs
diff --git a/readme_docs/CommonModels.md b/readme_docs/CommonModels.md
@@ -0,0 +1,13 @@
+# <a id="IndicoV2_CommonModels"></a> Namespace IndicoV2.CommonModels
+
+### Classes
+
+ [PageInfo](IndicoV2.CommonModels.Pagination.PageInfo.md)
+
+Represents graphql pagination cursor.
+
+### Interfaces
+
+ [IHasCursor<T\>](IndicoV2.CommonModels.Pagination.IHasCursor\-1.md)
+
+ [IPrediction](IndicoV2.CommonModels.Predictions.IPrediction.md)
diff --git a/readme_docs/Dockerfile b/readme_docs/Dockerfile
@@ -0,0 +1,5 @@
+FROM mcr.microsoft.com/dotnet/sdk:7.0-alpine
+COPY . /indico-client-csharp
+WORKDIR /indico-client-csharp
+RUN apk update && apk add jq vim bash sed
+CMD ["sleep", "infinity"]
diff --git a/readme_docs/Extensions.md b/readme_docs/Extensions.md
@@ -0,0 +1,13 @@
+# <a id="IndicoV2_Extensions"></a> Namespace IndicoV2.Extensions
+
+### Namespaces
+
+ [IndicoV2.Extensions.SubmissionResult.Exceptions](IndicoV2.Extensions.SubmissionResult.Exceptions.md)
+
+### Interfaces
+
+ [IDataSetAwaiter](IndicoV2.Extensions.DataSets.IDataSetAwaiter.md)
+
+ [IJobAwaiter](IndicoV2.Extensions.Jobs.IJobAwaiter.md)
+
+ [ISubmissionResultAwaiter](IndicoV2.Extensions.SubmissionResult.ISubmissionResultAwaiter.md)
diff --git a/readme_docs/build_docs.sh b/readme_docs/build_docs.sh
@@ -0,0 +1,24 @@
+#!/usr/bin/env bash
+
+dotnet tool install docfx
+dotnet tool run docfx docfx_project/docfx.json 
+cd docfx_project
+rm apiV2/toc.yml
+
+for filename in apiV2/*.md; do
+    newfilename="$(basename $filename | sed -r 's|(.+)\.md|\1|; s|\.|-|g')"
+    newdir="$(basename $newfilename | sed -r 's|(IndicoV2\-\w+)\-.*|\1|')"
+    if [ $newfilename == $newdir ]; then
+        mv $filename "apiV2/$newfilename.md"
+    else
+        mkdir -p "apiV2/$newdir"
+        mv $filename "apiV2/$newdir/$newfilename.md"
+    fi
+done
+
+mv ../readme_docs/CommonModels.md ./apiV2/IndicoV2-CommonModels.md
+mv ../readme_docs/Extensions.md ./apiV2/IndicoV2-Extensions.md
+
+# fix links
+find apiV2 -type f -name '*.md' -print0 | xargs -0 sed -i -r 's|IHasCursor\\-1|IHasCursor-1|; s|(\(.+)\.md|\L\1|; s|\.|-|g'
+cd ..
diff --git a/readme_docs/harness-docs.yaml b/readme_docs/harness-docs.yaml
@@ -0,0 +1,110 @@
+pipeline:
+  projectIdentifier: IPA_Release
+  orgIdentifier: default
+  tags: {}
+  stages:
+    - stage:
+        name: Build Docs Container
+        identifier: Build_Docs_Container
+        description: ""
+        type: CI
+        spec:
+          cloneCodebase: true
+          execution:
+            steps:
+              - step:
+                  type: BuildAndPushDockerRegistry
+                  name: BuildAndPushDockerRegistry_1
+                  identifier: BuildAndPushDockerRegistry_1
+                  spec:
+                    connectorRef: account.harbor
+                    repo: harbor.devops.indico.io/indico/indico-client-csharp
+                    tags:
+                      - <+codebase.commitSha>
+                    dockerfile: readme_docs/Dockerfile
+          platform:
+            os: Linux
+            arch: Amd64
+          runtime:
+            type: Cloud
+            spec: {}
+    - stage:
+        name: Build Csharp Docs
+        identifier: Build_Python_Docs
+        description: ""
+        type: Custom
+        spec:
+          execution:
+            steps:
+              - step:
+                  type: Container
+                  name: PR To Readme
+                  identifier: PR_To_Readme
+                  spec:
+                    connectorRef: account.harbor
+                    image: harbor.devops.indico.io/indico/indico-client-csharp:<+codebase.commitSha>
+                    command: |
+                      cd /indico-client-csharp
+                      chmod +x ./readme_docs/build_docs.sh
+                      ./readme_docs/build_docs.sh
+
+                      cp -r docfx_project/apiV2 $DOCS_PATH
+                      git clone https://user:[email protected]/IndicoDataSolutions/indico-readme.git
+                      cd indico-readme
+                      git config --global user.email "[email protected]"
+                      git config --global user.name "cat-automation"
+                      git checkout -b docs-version-$TAG
+
+                      mkdir -p markdown
+                      cp -r $DOCS_PATH ./markdown/$LANGUAGE
+                      bash add_frontmatter_yaml.sh
+
+                      git add ./markdown/$LANGUAGE
+                      git commit -m "a set of doc changes"
+
+                      git push --set-upstream origin docs-version-$TAG
+                      curl -L \
+                        -X POST \
+                        -H "Accept: application/vnd.github+json" \
+                        -H "Authorization: Bearer $GITHUB_TOKEN" \
+                        -H "X-GitHub-Api-Version: 2022-11-28" \
+                        https://api.github.com/repos/IndicoDataSolutions/indico-readme/pulls \
+                        -d '{"title":"Amazing new feature","body":"Please pull these awesome changes in!","head":"docs-version-'"$TAG"'","base":"main"}'
+                    shell: Bash
+                    infrastructure:
+                      type: KubernetesDirect
+                      spec:
+                        connectorRef: account.Dev_Cluster
+                        namespace: default
+                        resources:
+                          limits:
+                            cpu: "0.5"
+                            memory: 500Mi
+                        annotations: {}
+                        labels: {}
+                        containerSecurityContext:
+                          capabilities:
+                            drop: []
+                            add: []
+                        nodeSelector: {}
+                    reports:
+                      type: JUnit
+                      spec:
+                        paths: []
+                    outputVariables: []
+                    envVariables:
+                      GITHUB_TOKEN: <+secrets.getValue("account.indicomachineuser_github_token")>
+                      TAG: <+codebase.commitSha>
+                      LANGUAGE: c-sharp
+                      README_API_KEY: <+secrets.getValue("meghanhickeyreadmepat")>
+                      DOCS_PATH: /harness/c-sharp
+                  timeout: 1m 30s
+        tags: {}
+  properties:
+    ci:
+      codebase:
+        connectorRef: account.Indico
+        repoName: indico-client-csharp
+        build: <+input>
+  identifier: Generate_CSharp_Docs
+  name: Generate CSharp Docs
diff --git a/scripts/build_docs.sh b/scripts/build_docs.sh
diff --git a/scripts/test.sh → test.sh b/scripts/test.sh → test.sh