Skip to content

Commit 68e56f7

Browse files
CMCDragonkaiCMCDragonkai
committed
npm: aligned on package.json
lint: react imports are StudlyCased chore: aligned README.md ci: added the custom deploy script chore: align on `docusaurus.config.ts` ci: align on `.gitlab-ci.yml` fix: remove `pluginClientRedirects` as it is not being used fix: avoid warning on broken links
1 parent 3884391 commit 68e56f7

File tree

13 files changed

+1125
-621
lines changed

13 files changed

+1125
-621
lines changed

‎.eslintrc‎

Lines changed: 0 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -126,12 +126,6 @@
126126
"@typescript-eslint/await-thenable": ["error"],
127127
"@typescript-eslint/naming-convention": [
128128
"error",
129-
{
130-
"selector": "default",
131-
"format": ["camelCase"],
132-
"leadingUnderscore": "allow",
133-
"trailingUnderscore": "allowSingleOrDouble"
134-
},
135129
{
136130
"selector": "function",
137131
"format": ["camelCase", "PascalCase"],

‎.gitattributes‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
11
images/** filter=lfs diff=lfs merge=lfs -text
2+
files/** filter=lfs diff=lfs merge=lfs -text
23
images/LICENSE filter= merge= diff= text
34
images/README.md filter= merge= diff= text
4-
files/** filter=lfs diff=lfs merge=lfs -text

‎.gitlab-ci.yml‎

Lines changed: 144 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -10,9 +10,9 @@ variables:
1010
GH_PROJECT_PATH: "MatrixAI/${CI_PROJECT_NAME}"
1111
GH_PROJECT_URL: "https://${GITHUB_TOKEN}@github.com/${GH_PROJECT_PATH}.git"
1212
# Cache .npm
13-
NPM_CONFIG_CACHE: "${CI_PROJECT_DIR}/tmp/npm"
13+
npm_config_cache: "${CI_PROJECT_DIR}/tmp/npm"
1414
# Prefer offline node module installation
15-
NPM_CONFIG_PREFER_OFFLINE: "true"
15+
npm_config_prefer_offline: "true"
1616

1717
default:
1818
interruptible: true
@@ -31,6 +31,7 @@ cache:
3131
stages:
3232
- check # Linting, unit tests
3333
- build # Cross-platform library compilation, unit tests
34+
- integration # Cross-platform application bundling, integration tests, and pre-release
3435
- release # Cross-platform distribution and deployment
3536

3637
image: registry.gitlab.com/matrixai/engineering/maintenance/gitlab-runner
@@ -39,16 +40,19 @@ check:lint:
3940
stage: check
4041
needs: []
4142
script:
42-
- echo 'Perform linting'
43+
- >
44+
nix-shell --arg ci true --run $'
45+
npm run lint;
46+
'
4347
rules:
44-
# Runs on master commits
45-
- if: $CI_COMMIT_BRANCH == 'master'
48+
# Runs on feature and staging commits
49+
- if: $CI_COMMIT_BRANCH =~ /^(?:feature.*|staging)$/
4650

47-
build:docs:
48-
stage: build
51+
check:build:
52+
stage: check
4953
needs: []
5054
script:
51-
- echo 'Perform static docs generation'
55+
- echo 'Perform build'
5256
- >
5357
nix-shell --arg ci true --run $'
5458
npm run build;
@@ -58,22 +62,149 @@ build:docs:
5862
paths:
5963
- ./public
6064
rules:
61-
# Runs on master commits
62-
- if: $CI_COMMIT_BRANCH == 'master'
65+
# Runs on feature, staging and master commits
66+
- if: $CI_COMMIT_BRANCH =~ /^(?:feature.*|staging)$/
67+
68+
check:deployment:
69+
stage: check
70+
needs:
71+
- check:build
72+
# Don't interrupt deploying job
73+
interruptible: false
74+
# Requires mutual exclusion
75+
resource_group: check:deployment
76+
environment:
77+
name: "feature/$CI_COMMIT_REF_SLUG"
78+
url: "https://$CI_COMMIT_REF_SLUG.dev.polykey.com/docs/"
79+
deployment_tier: 'development'
80+
on_stop: check:deployment:stop
81+
auto_stop_in: 1 week
82+
script:
83+
- echo 'Perform service deployment for feature'
84+
- >
85+
nix-shell --arg ci true --run $'
86+
npm run deploy -- \
87+
--feature "$CI_COMMIT_REF_SLUG" \
88+
--env "$CI_COMMIT_REF_SLUG";
89+
'
90+
rules:
91+
# Runs on feature commits
92+
- if: $CI_COMMIT_BRANCH =~ /^feature.*$/
93+
94+
check:deployment:stop:
95+
stage: check
96+
# Don't interrupt deploying job
97+
interruptible: false
98+
# Requires mutual exclusion
99+
resource_group: check:deployment:stop
100+
environment:
101+
name: "feature/$CI_COMMIT_REF_SLUG"
102+
action: stop
103+
script:
104+
- echo 'Perform service deployment for feature'
105+
- >
106+
nix-shell --arg ci true --run $'
107+
wrangler delete --name "polykey-docs-dev-$CI_COMMIT_REF_SLUG" --force;
108+
'
109+
rules:
110+
# Manually runnable on feature commits
111+
- if: $CI_COMMIT_BRANCH =~ /^feature.*$/
112+
when: manual
113+
114+
build:merge:
115+
stage: build
116+
needs: []
117+
# Requires mutual exclusion
118+
resource_group: build:merge
119+
script:
120+
# Required for `gh pr create`
121+
- git remote add upstream "$GH_PROJECT_URL"
122+
- >
123+
nix-shell --arg ci true --run $'
124+
gh pr create \
125+
--head staging \
126+
--base master \
127+
--title "ci: merge staging to master" \
128+
--body "This is an automatic PR generated by the pipeline CI/CD. This will be automatically fast-forward merged if successful." \
129+
--assignee "@me" \
130+
--no-maintainer-edit \
131+
--repo "$GH_PROJECT_PATH" || true;
132+
printf "Pipeline Attempt on ${CI_PIPELINE_ID} for ${CI_COMMIT_SHA}\n\n${CI_PIPELINE_URL}" \
133+
| gh pr comment staging \
134+
--body-file - \
135+
--repo "$GH_PROJECT_PATH";
136+
'
137+
rules:
138+
# Runs on staging commits
139+
- if: $CI_COMMIT_BRANCH == 'staging'
140+
141+
integration:deployment:
142+
stage: integration
143+
needs:
144+
- check:build
145+
# Don't interrupt deploying job
146+
interruptible: false
147+
# Requires mutual exclusion
148+
resource_group: integration:deployment
149+
environment:
150+
name: 'staging'
151+
url: 'https://staging.polykey.com/docs/'
152+
deployment_tier: 'staging'
153+
script:
154+
- echo 'Perform service deployment for staging'
155+
- >
156+
nix-shell --arg ci true --run $'
157+
npm run deploy -- --env staging;
158+
'
159+
rules:
160+
# Runs on staging commits
161+
- if: $CI_COMMIT_BRANCH == 'staging'
162+
163+
integration:merge:
164+
stage: integration
165+
needs:
166+
- build:merge
167+
- integration:deployment
168+
# Requires mutual exclusion
169+
resource_group: integration:merge
170+
variables:
171+
# Ensure that CI/CD is fetching all commits
172+
# this is necessary to checkout origin/master
173+
# and to also merge origin/staging
174+
GIT_DEPTH: 0
175+
script:
176+
- >
177+
nix-shell --arg ci true --run $'
178+
printf "Pipeline Succeeded on ${CI_PIPELINE_ID} for ${CI_COMMIT_SHA}\n\n${CI_PIPELINE_URL}" \
179+
| gh pr comment staging \
180+
--body-file - \
181+
--repo "$GH_PROJECT_PATH";
182+
'
183+
- git remote add upstream "$GH_PROJECT_URL"
184+
- git checkout origin/master
185+
# Merge up to the current commit (not the latest commit)
186+
- git merge --ff-only "$CI_COMMIT_SHA"
187+
- git push upstream HEAD:master
188+
rules:
189+
# Runs on staging commits
190+
- if: $CI_COMMIT_BRANCH == 'staging'
63191

64192
release:deployment:
65193
stage: release
194+
# Only needs check:build from the staging branch pipeline
66195
needs:
67-
- check:lint
68-
- build:docs
196+
- project: $CI_PROJECT_PATH
197+
job: check:build
198+
ref: staging
199+
artifacts: true
69200
# Don't interrupt deploying job
70201
interruptible: false
71202
# Requires mutual exclusion
72203
resource_group: release:deployment
73204
environment:
74205
name: 'production'
206+
url: 'https://polykey.com/docs/'
75207
deployment_tier: 'production'
76-
url: 'https://polykey.com/docs'
77208
script:
78209
- echo 'Perform service deployment for production'
79210
- >

‎README.md‎

Lines changed: 15 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -36,6 +36,13 @@ Pro-tip, if we need to make sure files that were accidentally not put into LFS m
3636

3737
```sh
3838
git lfs migrate import --include="images/**" --everything
39+
git lfs migrate import --include="files/**" --everything
40+
```
41+
42+
Sometimes when you change branches, certain LFS references may not yet be resolved, in those cases you should just use (such as doing a `git lfs migrate import`):
43+
44+
```sh
45+
git lfs pull
3946
```
4047

4148
## Contributing
@@ -46,15 +53,15 @@ Because we use docusaurus, we can choose to write in markdown, TSX or MDX.
4653

4754
Sometimes markdown syntax just doesn't cut it, and HTML syntax needs to be used.
4855

49-
While `docusaurus` is flexible, GitHub is not.
56+
While `docusaurus` is flexible, GitHub/GitLab is not.
5057

51-
GitHub will process the markdown and then sanitizes the HTML: https://github.com/github/markup#github-markup.
58+
GitHub/GitLab will process the markdown and then sanitizes the HTML: https://github.com/github/markup#github-markup.
5259

5360
There is a limited set of HTML tags are here: https://github.com/gjtorikian/html-pipeline/blob/03ae30d713199c2562951d627b98b75dc16939e4/lib/html/pipeline/sanitization_filter.rb#L40-L49
5461

5562
Furthermore not all attributes are kept. The `style` attribute for example is filtered out.
5663

57-
The most common styling attributes to be used will most likely be `align`, `width`, and `height`. See: https://davidwells.io/snippets/how-to-align-images-in-markdown
64+
The most common styling attributes to be used will most likely be `align`, `width`, and `height`. See: https://davidwells.io/snippets/how-to-align-images-in-markdown
5865

5966
### Linking Assets (files, images)
6067

@@ -67,9 +74,9 @@ Markdown supports 2 ways of referencing images:
6774

6875
The former is markdown syntax, the latter is HTML tag.
6976

70-
In order to maintain portability, we always use absolute paths. This works on both GitHub markdown rendering and also for `docusaurus`.
77+
In order to maintain portability, we always use absolute paths. This works on both GitHub/GitLab markdown rendering and also for `docusaurus`.
7178

72-
On GitHub, which renders the markdown directly, the relative paths are considered relative to the location of the markdown file referencing the path. The absolute paths are considered relative to the root of the project repository. Therefore because `images` directory is located at the project root, it ends up being routable.
79+
On GitHub/GitLab, which renders the markdown directly, the relative paths are considered relative to the location of the markdown file referencing the path. The absolute paths are considered relative to the root of the project repository. Therefore because `images` directory is located at the project root, it ends up being routable.
7380

7481
With `docusaurus`, the absolute paths are looked up relative to `static` directory. Inside the `static` directory we have created symlinks pointing back to `../images`. This allows `docusaurus` to also resolve these paths which will be copied into the `/build/` directory.
7582

@@ -79,19 +86,19 @@ Note that `docusaurus` doesn't do any special rendering for HTML tags, it uses t
7986
<img src={require('/images/foobar.png').default} />
8087
```
8188

82-
However this does not work in GitHub. So this is not recommended to use.
89+
However this does not work in GitHub/GitLab. So this is not recommended to use.
8390

8491
Therefore if you want to add inline styles to an image and still use markdown syntax so you get the benefit of `docusaurus` asset processing, the styles must be applied outside the image reference in a surrounding tag:
8592

86-
```ms
93+
```md
8794
<div align="center">
8895

8996
![](/images/foobar.png)
9097

9198
</div>
9299
```
93100

94-
Take note of the whitespace newlines between, if no newlines are used, GitHub will interpret this as all HTML. Also note that `<p></p>` will not work.
101+
Take note of the whitespace newlines between, if no newlines are used, GitHub/GitLab will interpret this as all HTML. Also note that `<p></p>` will not work.
95102

96103
Note that this won't work for resizing the images unfortunately. You have to apply the `width` attribute directly to the `<img />` tag. See: https://github.com/facebook/docusaurus/discussions/6465 for more information.
97104

‎docusaurus.config.ts‎

Lines changed: 23 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,8 @@
11
import type { Config } from '@docusaurus/types';
2-
import type { UserThemeConfig } from '@docusaurus/theme-common';
32
import type { Options as PluginDocsOptions } from '@docusaurus/plugin-content-docs';
4-
import type { Options as ThemeClassicOptions } from '@docusaurus/theme-classic';
3+
import type { Options as PluginGTagOptions } from '@docusaurus/plugin-google-gtag';
4+
import type { Options as ThemeOptions } from '@docusaurus/theme-classic';
5+
import type { UserThemeConfig } from '@docusaurus/theme-common';
56
import { visit } from 'unist-util-visit';
67
import { themes as prismThemes } from 'prism-react-renderer';
78

@@ -16,7 +17,7 @@ const darkCodeTheme = prismThemes.dracula;
1617
* Note that this is a hack, and it's ideal to instead prefer using `require`.
1718
* However those images would not be viewable in the GitHub markdown.
1819
*/
19-
const remarkImageSrcWithRequire = () => {
20+
const remarkImageSrcWithDocsPrefix = () => {
2021
return (tree) => {
2122
visit(tree, 'mdxJsxFlowElement', (node) => {
2223
if (node.name === 'img') {
@@ -41,20 +42,26 @@ const pluginDocs: [string, PluginDocsOptions] = [
4142
path: 'docs',
4243
routeBasePath: '/',
4344
sidebarPath: './sidebars.ts',
44-
remarkPlugins: [remarkImageSrcWithRequire],
45+
remarkPlugins: [remarkImageSrcWithDocsPrefix],
4546
include: ['**/*.md', '**/*.mdx'],
4647
exclude: ['**/_*.{js,jsx,ts,tsx,md,mdx}', '**/_*/**', '**/.**'],
4748
},
4849
];
4950

50-
const pluginThemeClassic: [string, ThemeClassicOptions] = [
51-
'@docusaurus/theme-classic',
51+
const pluginGTag: [string, PluginGTagOptions] = [
52+
'@docusaurus/plugin-google-gtag',
5253
{
53-
customCss: './src/css/custom.css',
54+
trackingID: 'G-GSMHXNB32E',
55+
anonymizeIP: false,
5456
},
5557
];
5658

57-
const pluginClientRedirects = ['@docusaurus/plugin-client-redirects', {}];
59+
const pluginTheme: [string, ThemeOptions] = [
60+
'@docusaurus/theme-classic',
61+
{
62+
customCss: require.resolve('./src/css/custom.css'),
63+
},
64+
];
5865

5966
const themeConfig: UserThemeConfig = {
6067
colorMode: {
@@ -127,7 +134,7 @@ const themeConfig: UserThemeConfig = {
127134
},
128135
{
129136
label: 'Docs',
130-
to: '/docs/'
137+
to: '/docs/',
131138
},
132139
{
133140
label: 'Mainnet Network',
@@ -216,18 +223,22 @@ const config: Config = {
216223
title: 'Polykey Documentation',
217224
tagline: 'Tutorials, How-To Guides, Theory and Reference',
218225
url: 'https://polykey.com',
226+
// The `baseUrl` always must end with a trailing slash.
219227
baseUrl: '/docs/',
220228
onBrokenLinks: 'warn',
221229
onBrokenMarkdownLinks: 'warn',
222-
// The `baseUrl` always must end with a trailing slash.
223-
trailingSlash: false,
230+
// This ensures that `/x.md` is generated as `/x/index.html` and not `/x.html`.
231+
// Which is the expected directory layout for most web servers.
232+
trailingSlash: undefined,
224233
favicon: 'images/polykey-favicon.png',
234+
organizationName: 'MatrixAI',
235+
projectName: 'PolyKey-Docs',
225236
i18n: {
226237
defaultLocale: 'en',
227238
locales: ['en'],
228239
},
229240
staticDirectories: ['static'],
230-
plugins: [pluginDocs, pluginThemeClassic, pluginClientRedirects],
241+
plugins: [pluginDocs, pluginTheme, pluginGTag],
231242
themeConfig,
232243
};
233244

0 commit comments

Comments
 (0)