Skip to content

Commit 0096e22

Browse files
meghanhickeymeghanhickey
authored
[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
1 parent 1ed13b6 commit 0096e22

11 files changed

+208
-33
lines changed

‎docfx_project/docfx.json

+3-8
Original file line numberDiff line numberDiff line change
@@ -5,19 +5,14 @@
55
{
66
"src": "../",
77
"files": [
8-
"IndicoV2*/**.csproj"
9-
],
10-
"exclude": [
11-
"docfx_project/**",
12-
"*Tests/**",
13-
"IndicoV2.V1Adapters/**",
14-
"IndicoV2.StrawberryShake/**"
8+
"IndicoV2.Abstractions/**.csproj"
159
]
1610
}
1711
],
1812
"dest": "apiV2",
1913
"disableGitFeatures": false,
20-
"outputFormat": "markdown"
14+
"outputFormat": "markdown",
15+
"filter": "filterConfig.yml"
2116
}
2217
]
2318
}

‎docfx_project/filterConfig.yml

+11
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
apiRules:
2+
- exclude:
3+
uidRegex: IndicoV2\.Workflows\.Models\.Workflow
4+
- exclude:
5+
uidRegex: IndicoV2\.Submissions\.Models\.SubmissionSs
6+
- exclude:
7+
uidRegex: IndicoV2\.Submissions\.Models\.FilterConverter
8+
- exclude:
9+
uidRegex: IndicoV2\.Ocr\.Models\.ExtractionJobResult
10+
- exclude:
11+
uidRegex: IndicoV2\.CommonModels\.Pagination\.HasCursor

‎docs.Dockerfile

-16
This file was deleted.

‎harness-docs.yaml

+29-5
Original file line numberDiff line numberDiff line change
@@ -21,7 +21,7 @@ pipeline:
2121
repo: harbor.devops.indico.io/indico/indico-client-csharp
2222
tags:
2323
- <+codebase.commitSha>
24-
dockerfile: docs.Dockerfile
24+
dockerfile: readme_docs/docs.Dockerfile
2525
platform:
2626
os: Linux
2727
arch: Amd64
@@ -45,7 +45,31 @@ pipeline:
4545
image: harbor.devops.indico.io/indico/indico-client-csharp:<+codebase.commitSha>
4646
command: |
4747
cd /indico-client-csharp
48-
./scripts/build_docs.sh
48+
chmod +x ./readme_docs/build_docs.sh
49+
./readme_docs/build_docs.sh
50+
51+
cp -r docfx_project/apiV2 $DOCS_PATH
52+
git clone https://user:[email protected]/IndicoDataSolutions/indico-readme.git
53+
cd indico-readme
54+
git config --global user.email "[email protected]"
55+
git config --global user.name "cat-automation"
56+
git checkout -b docs-version-$TAG
57+
58+
mkdir -p markdown
59+
cp -r $DOCS_PATH ./markdown/$LANGUAGE
60+
bash add_frontmatter_yaml.sh
61+
62+
git add ./markdown/$LANGUAGE
63+
git commit -m "a set of doc changes"
64+
65+
git push --set-upstream origin docs-version-$TAG
66+
curl -L \
67+
-X POST \
68+
-H "Accept: application/vnd.github+json" \
69+
-H "Authorization: Bearer $GITHUB_TOKEN" \
70+
-H "X-GitHub-Api-Version: 2022-11-28" \
71+
https://api.github.com/repos/IndicoDataSolutions/indico-readme/pulls \
72+
-d '{"title":"Amazing new feature","body":"Please pull these awesome changes in!","head":"docs-version-'"$TAG"'","base":"main"}'
4973
shell: Bash
5074
infrastructure:
5175
type: KubernetesDirect
@@ -71,9 +95,9 @@ pipeline:
7195
envVariables:
7296
GITHUB_TOKEN: <+secrets.getValue("readmeghpat")>
7397
TAG: <+codebase.commitSha>
74-
LANGUAGE: chsarp
98+
LANGUAGE: c-sharp
7599
README_API_KEY: <+secrets.getValue("meghanhickeyreadmepat")>
76-
DOCS_PATH: /harness/csharp
100+
DOCS_PATH: /harness/c-sharp
77101
timeout: 1m 30s
78102
tags: {}
79103
properties:
@@ -83,4 +107,4 @@ pipeline:
83107
repoName: indico-client-csharp
84108
build: <+input>
85109
identifier: Generate_CSharp_Docs
86-
name: Generate CSharp Docs
110+
name: Generate CSharp Docs

‎readme_docs/CommonModels.md

+13
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
# <a id="IndicoV2_CommonModels"></a> Namespace IndicoV2.CommonModels
2+
3+
### Classes
4+
5+
[PageInfo](IndicoV2.CommonModels.Pagination.PageInfo.md)
6+
7+
Represents graphql pagination cursor.
8+
9+
### Interfaces
10+
11+
[IHasCursor<T\>](IndicoV2.CommonModels.Pagination.IHasCursor\-1.md)
12+
13+
[IPrediction](IndicoV2.CommonModels.Predictions.IPrediction.md)

‎readme_docs/Dockerfile

+5
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
FROM mcr.microsoft.com/dotnet/sdk:7.0-alpine
2+
COPY . /indico-client-csharp
3+
WORKDIR /indico-client-csharp
4+
RUN apk update && apk add jq vim bash sed
5+
CMD ["sleep", "infinity"]

‎readme_docs/Extensions.md

+13
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
# <a id="IndicoV2_Extensions"></a> Namespace IndicoV2.Extensions
2+
3+
### Namespaces
4+
5+
[IndicoV2.Extensions.SubmissionResult.Exceptions](IndicoV2.Extensions.SubmissionResult.Exceptions.md)
6+
7+
### Interfaces
8+
9+
[IDataSetAwaiter](IndicoV2.Extensions.DataSets.IDataSetAwaiter.md)
10+
11+
[IJobAwaiter](IndicoV2.Extensions.Jobs.IJobAwaiter.md)
12+
13+
[ISubmissionResultAwaiter](IndicoV2.Extensions.SubmissionResult.ISubmissionResultAwaiter.md)

‎readme_docs/build_docs.sh

+24
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
#!/usr/bin/env bash
2+
3+
dotnet tool install docfx
4+
dotnet tool run docfx docfx_project/docfx.json
5+
cd docfx_project
6+
rm apiV2/toc.yml
7+
8+
for filename in apiV2/*.md; do
9+
newfilename="$(basename $filename | sed -r 's|(.+)\.md|\1|; s|\.|-|g')"
10+
newdir="$(basename $newfilename | sed -r 's|(IndicoV2\-\w+)\-.*|\1|')"
11+
if [ $newfilename == $newdir ]; then
12+
mv $filename "apiV2/$newfilename.md"
13+
else
14+
mkdir -p "apiV2/$newdir"
15+
mv $filename "apiV2/$newdir/$newfilename.md"
16+
fi
17+
done
18+
19+
mv ../readme_docs/CommonModels.md ./apiV2/IndicoV2-CommonModels.md
20+
mv ../readme_docs/Extensions.md ./apiV2/IndicoV2-Extensions.md
21+
22+
# fix links
23+
find apiV2 -type f -name '*.md' -print0 | xargs -0 sed -i -r 's|IHasCursor\\-1|IHasCursor-1|; s|(\(.+)\.md|\L\1|; s|\.|-|g'
24+
cd ..

‎readme_docs/harness-docs.yaml

+110
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,110 @@
1+
pipeline:
2+
projectIdentifier: IPA_Release
3+
orgIdentifier: default
4+
tags: {}
5+
stages:
6+
- stage:
7+
name: Build Docs Container
8+
identifier: Build_Docs_Container
9+
description: ""
10+
type: CI
11+
spec:
12+
cloneCodebase: true
13+
execution:
14+
steps:
15+
- step:
16+
type: BuildAndPushDockerRegistry
17+
name: BuildAndPushDockerRegistry_1
18+
identifier: BuildAndPushDockerRegistry_1
19+
spec:
20+
connectorRef: account.harbor
21+
repo: harbor.devops.indico.io/indico/indico-client-csharp
22+
tags:
23+
- <+codebase.commitSha>
24+
dockerfile: readme_docs/Dockerfile
25+
platform:
26+
os: Linux
27+
arch: Amd64
28+
runtime:
29+
type: Cloud
30+
spec: {}
31+
- stage:
32+
name: Build Csharp Docs
33+
identifier: Build_Python_Docs
34+
description: ""
35+
type: Custom
36+
spec:
37+
execution:
38+
steps:
39+
- step:
40+
type: Container
41+
name: PR To Readme
42+
identifier: PR_To_Readme
43+
spec:
44+
connectorRef: account.harbor
45+
image: harbor.devops.indico.io/indico/indico-client-csharp:<+codebase.commitSha>
46+
command: |
47+
cd /indico-client-csharp
48+
chmod +x ./readme_docs/build_docs.sh
49+
./readme_docs/build_docs.sh
50+
51+
cp -r docfx_project/apiV2 $DOCS_PATH
52+
git clone https://user:[email protected]/IndicoDataSolutions/indico-readme.git
53+
cd indico-readme
54+
git config --global user.email "[email protected]"
55+
git config --global user.name "cat-automation"
56+
git checkout -b docs-version-$TAG
57+
58+
mkdir -p markdown
59+
cp -r $DOCS_PATH ./markdown/$LANGUAGE
60+
bash add_frontmatter_yaml.sh
61+
62+
git add ./markdown/$LANGUAGE
63+
git commit -m "a set of doc changes"
64+
65+
git push --set-upstream origin docs-version-$TAG
66+
curl -L \
67+
-X POST \
68+
-H "Accept: application/vnd.github+json" \
69+
-H "Authorization: Bearer $GITHUB_TOKEN" \
70+
-H "X-GitHub-Api-Version: 2022-11-28" \
71+
https://api.github.com/repos/IndicoDataSolutions/indico-readme/pulls \
72+
-d '{"title":"Amazing new feature","body":"Please pull these awesome changes in!","head":"docs-version-'"$TAG"'","base":"main"}'
73+
shell: Bash
74+
infrastructure:
75+
type: KubernetesDirect
76+
spec:
77+
connectorRef: account.Dev_Cluster
78+
namespace: default
79+
resources:
80+
limits:
81+
cpu: "0.5"
82+
memory: 500Mi
83+
annotations: {}
84+
labels: {}
85+
containerSecurityContext:
86+
capabilities:
87+
drop: []
88+
add: []
89+
nodeSelector: {}
90+
reports:
91+
type: JUnit
92+
spec:
93+
paths: []
94+
outputVariables: []
95+
envVariables:
96+
GITHUB_TOKEN: <+secrets.getValue("account.indicomachineuser_github_token")>
97+
TAG: <+codebase.commitSha>
98+
LANGUAGE: c-sharp
99+
README_API_KEY: <+secrets.getValue("meghanhickeyreadmepat")>
100+
DOCS_PATH: /harness/c-sharp
101+
timeout: 1m 30s
102+
tags: {}
103+
properties:
104+
ci:
105+
codebase:
106+
connectorRef: account.Indico
107+
repoName: indico-client-csharp
108+
build: <+input>
109+
identifier: Generate_CSharp_Docs
110+
name: Generate CSharp Docs

‎scripts/build_docs.sh

-4
This file was deleted.

‎scripts/test.sh ‎test.sh

File renamed without changes.

0 commit comments

Comments
 (0)