Skip to content

Commit

Permalink
Browse files Browse the repository at this point in the history
…ting-guide

* HDDS-9225-website-v2:
  HDDS-9567. Add GitHub Actions license header check for relevant files. (#86)
  HDDS-10506. Reduce directory iterations in sidebar check (#85)
  HDDS-9866. Add GitHub Actions checks for consistent Docusaurus formatting. (#84)
  • Loading branch information
errose28 committed Mar 26, 2024
2 parents 22201d2 + 0126e8a commit 7f28550
Show file tree
Hide file tree
Showing 25 changed files with 491 additions and 26 deletions.
17 changes: 17 additions & 0 deletions .dockerignore
Original file line number Diff line number Diff line change
@@ -1,3 +1,20 @@
# Licensed to the Apache Software Foundation (ASF) under one
# or more contributor license agreements. See the NOTICE file
# distributed with this work for additional information
# regarding copyright ownership. The ASF licenses this file
# to you under the Apache License, Version 2.0 (the
# "License"); you may not use this file except in compliance
# with the License. You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing,
# software distributed under the License is distributed on an
# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
# KIND, either express or implied. See the License for the
# specific language governing permissions and limitations
# under the License.

node_modules
build
.docusaurus
Expand Down
17 changes: 17 additions & 0 deletions .github/resource/category.schema.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,17 @@
{
"$schema": "http://json-schema.org/draft-07/schema#",
"$id": "https://ozone.apache.org/category.schema.json",
"title": "Category",
"description": "Validates an allowed subset of keys in Docusaurus _category_.yml files.",
"type": "object",
"properties": {
"label": {
"description": "The name of this section shown in the docs sidebar.",
"type": "string"
}
},
"required": [
"label"
],
"additionalProperties": false
}
23 changes: 23 additions & 0 deletions .github/resource/frontmatter.schema.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,23 @@
{
"$schema": "http://json-schema.org/draft-07/schema#",
"$id": "https://ozone.apache.org/frontmatter.schema.json",
"title": "Frontmatter",
"description": "Validates an allowed subset of Docusaurus docs frontmatter.",
"type": [ "object", "null" ],
"properties": {
"sidebar_label": {
"type": "string"
},
"slug": {
"description": "Only use slug to specify the base URL for documentation.",
"type": "string",
"enum": [ "/" ]
},
"draft": {
"description": "Makes pages for incomplete features only visible in development mode.",
"type": "boolean"
}
},
"additionalProperties": false
}

46 changes: 46 additions & 0 deletions .github/scripts/sidebar.sh
Original file line number Diff line number Diff line change
@@ -0,0 +1,46 @@
#!/usr/bin/env sh
# Licensed to the Apache Software Foundation (ASF) under one
# or more contributor license agreements. See the NOTICE file
# distributed with this work for additional information
# regarding copyright ownership. The ASF licenses this file
# to you under the Apache License, Version 2.0 (the
# "License"); you may not use this file except in compliance
# with the License. You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing,
# software distributed under the License is distributed on an
# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
# KIND, either express or implied. See the License for the
# specific language governing permissions and limitations
# under the License.

# Validates docusaurus _category_.yml files used to configure the docs sidebar.
# Each docs subdirectory should have a _category_.yml file, and it must follow the defined schema.
# The schema is more restrictive than what Docusaurus allows, and can be used to disallow keys or require all category
# files to define the same keys.

rc=0

root="$(git rev-parse --show-toplevel)"
schema="$root"/.github/resource/category.schema.json

# Make sure all docs directories have a category sidebar file.
for child in $(find "$root"/docs/* -type d); do
category_file="$child/_category_.yml"
if [ ! -f "$category_file" ]; then
echo "_category_.yml is required for docs subdirectory $child" 1>&2
rc=1
fi
done

[ "$rc" = 0 ] || exit $rc

# If all category files are present, make sure they follow the schema.
if ! pnpm ajv validate -s "$schema" -d "$root/docs/**/_category_.yml" 1>/dev/null; then
rc=1
echo "Sidebar configuration validation failed against JSON schema $schema" 1>&2
fi

exit "$rc"
26 changes: 26 additions & 0 deletions .github/workflows/static.yml
Original file line number Diff line number Diff line change
Expand Up @@ -32,6 +32,13 @@ env:
node_version: 20

jobs:
license:
runs-on: ubuntu-latest
steps:
- name: Checkout project
uses: actions/checkout@v4
- name: Check Apache license headers
uses: apache/skywalking-eyes@v0.5.0
file-names:
runs-on: ubuntu-latest
steps:
Expand Down Expand Up @@ -83,3 +90,22 @@ jobs:
working-directory: ${{ env.script_dir }}
run: |
./markdownlint.sh
check-sidebar:
runs-on: ubuntu-latest
steps:
- name: Checkout project
uses: actions/checkout@v4
- name: Enable corepack
run: |
corepack enable
- name: Use Node.js ${{ env.node_version }}
uses: actions/setup-node@v4
with:
node-version: ${{ env.node_version }}
cache: pnpm
- name: Install pnpm dependencies
run: pnpm install --dev
- name: Run docs sidebar check
working-directory: ${{ env.script_dir }}
run: |
./sidebar.sh
17 changes: 17 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
@@ -1,3 +1,20 @@
# Licensed to the Apache Software Foundation (ASF) under one
# or more contributor license agreements. See the NOTICE file
# distributed with this work for additional information
# regarding copyright ownership. The ASF licenses this file
# to you under the Apache License, Version 2.0 (the
# "License"); you may not use this file except in compliance
# with the License. You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing,
# software distributed under the License is distributed on an
# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
# KIND, either express or implied. See the License for the
# specific language governing permissions and limitations
# under the License.

# Dependencies
/node_modules

Expand Down
41 changes: 41 additions & 0 deletions .licenserc.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,41 @@
# Licensed to the Apache Software Foundation (ASF) under one
# or more contributor license agreements. See the NOTICE file
# distributed with this work for additional information
# regarding copyright ownership. The ASF licenses this file
# to you under the Apache License, Version 2.0 (the
# "License"); you may not use this file except in compliance
# with the License. You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing,
# software distributed under the License is distributed on an
# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
# KIND, either express or implied. See the License for the
# specific language governing permissions and limitations
# under the License.

header:
license:
spdx-id: Apache-2.0
copyright-owner: Apache Software Foundation

# See https://www.apache.org/legal/src-headers.html#faq-exceptions
# Files already in .gitignore are ignored by default.
paths-ignore:
- LICENSE.txt
# Json does not support comments.
- "**/*.json"
# Docs content does not require headers.
# See examples on https://github.com/apache/www-site and the skywalking-eyes recommended configuration for
# Apache projects at https://github.com/apache/skywalking-eyes?tab=readme-ov-file#github-actions
- "**/*.md"
- "**/_category_.yml"
- pnpm-lock.yaml

# Do not comment on pull requests.
comment: never

dependency:
files:
- package.json
6 changes: 3 additions & 3 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -119,7 +119,7 @@ Docusaurus provides many options for laying out documentation pages and their me

- File names and therefore generated URLs should all be `kebab-case`.

- Let Docusaurus automatically generate the page's title from its top level markdown heading instead of using `title` in the frontmatter. This is different from the sidebar label or URL slug.
- Let Docusaurus automatically generate the page's title from its top level markdown heading instead of using `title` in the front matter. This is different from the sidebar label or URL slug.

- Use relative file paths for all links between pages.
- This keeps page links pointing to the current version of the documentation.
Expand Down Expand Up @@ -148,7 +148,7 @@ Docusaurus provides many options for laying out documentation pages and their me
Object Store Bucket Layout
```

- Sidebar labels are automatically generated from page titles. To use a different sidebar label, use the `sidebar_label` property in the page's frontmatter.
- Sidebar labels are automatically generated from page titles. To use a different sidebar label, use the `sidebar_label` property in the page's front matter.

- Don't rely on Ozone specific acronyms in the sidebar. This makes docs navigation more beginner friendly.
- For example, the pages on bucket layouts may be organized as:
Expand Down Expand Up @@ -197,7 +197,7 @@ The file names and content of all markdown pages are checked for spelling mistak

- **Option 1:** If the word is relevant for the whole Ozone project, add it to the `words` list in *cspell.yaml* so that it is considered valid.

- **Option 2:** If the word is only relevant for one specific page, add an [inline directive](https://cspell.org/configuration/document-settings/) as a comment in the markdown frontmatter of that page only.
- **Option 2:** If the word is only relevant for one specific page, add an [inline directive](https://cspell.org/configuration/document-settings/) as a comment in the markdown front matter of that page only.

### Updating Graphics

Expand Down
19 changes: 19 additions & 0 deletions babel.config.js
Original file line number Diff line number Diff line change
@@ -1,3 +1,22 @@
/*
* Licensed to the Apache Software Foundation (ASF) under one
* or more contributor license agreements. See the NOTICE file
* distributed with this work for additional information
* regarding copyright ownership. The ASF licenses this file
* to you under the Apache License, Version 2.0 (the
* "License"); you may not use this file except in compliance
* with the License. You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing,
* software distributed under the License is distributed on an
* "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
* KIND, either express or implied. See the License for the
* specific language governing permissions and limitations
* under the License.
*/

module.exports = {
presets: [require.resolve('@docusaurus/core/lib/babel/preset')],
};
1 change: 0 additions & 1 deletion cspell.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -78,7 +78,6 @@ words:
- gpg
- sed
- mds
- frontmatter
- javadoc
# Misc words
- acking
Expand Down
4 changes: 2 additions & 2 deletions docs/07-system-internals/02-data-operations/04-hsync.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
---
# Page is accessible by direct link only in production site builds. It can be included in the sidebar when the feature is complete.
unlisted: true
# Page is available only in the development server. It can be included in production builds when the feature is complete.
draft: true
sidebar_label: HFlush and HSync
---

Expand Down
4 changes: 2 additions & 2 deletions docs/07-system-internals/07-features/05-ratis-streaming.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
---
# Page is accessible by direct link only in production site builds. It can be included in the sidebar when the feature is complete.
unlisted: true
# Page is available only in the development server. It can be included in production builds when the feature is complete.
draft: true
sidebar_label: Ratis Streaming
---

Expand Down
46 changes: 46 additions & 0 deletions docusaurus.config.js
Original file line number Diff line number Diff line change
@@ -1,6 +1,27 @@
/*
* Licensed to the Apache Software Foundation (ASF) under one
* or more contributor license agreements. See the NOTICE file
* distributed with this work for additional information
* regarding copyright ownership. The ASF licenses this file
* to you under the Apache License, Version 2.0 (the
* "License"); you may not use this file except in compliance
* with the License. You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing,
* software distributed under the License is distributed on an
* "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
* KIND, either express or implied. See the License for the
* specific language governing permissions and limitations
* under the License.
*/

// @ts-check
// Note: type annotations allow type checking and IDEs autocompletion

import Ajv from 'ajv';

const {themes} = require('prism-react-renderer');
const lightCodeTheme = themes.github;
const darkCodeTheme = themes.dracula;
Expand Down Expand Up @@ -34,6 +55,31 @@ const config = {
locales: ['en'],
},

markdown: {
// Validate markdown frontmatter against a more restrictive schema than what Docusaurus allows.
// This ensures all pages are using a minimal set of consistent keys.
// It can also be used to require all pages to define certain markdown front matter keys.
parseFrontMatter: async (params) => {
// Reuse the default parser.
const result = await params.defaultParseFrontMatter(params);

// Validate front matter against the schema.
const schemaPath = './.github/resource/frontmatter.schema.json';
const frontMatterSchema = require(schemaPath);
const ajv = new Ajv();
const validate = ajv.compile(frontMatterSchema);
const isValid = validate(result.frontMatter);

if (!isValid) {
console.error('Front matter validation error in', params.filePath + ':\n', validate.errors);
console.error('Front matter validation failed against JSON schema', schemaPath);
process.exit(1);
}

return result;
},
},

presets: [
[
'classic',
Expand Down
4 changes: 3 additions & 1 deletion package.json
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,8 @@
"clsx": "^2.1.0",
"prism-react-renderer": "^2.3.1",
"react": "^18.2.0",
"react-dom": "^18.2.0"
"react-dom": "^18.2.0",
"ajv": "^8.12.0"
},
"devDependencies": {
"@docusaurus/module-type-aliases": "3.1.1",
Expand All @@ -30,6 +31,7 @@
"@cspell/dict-java": "^5.0.6",
"@cspell/dict-markdown": "^2.0.1",
"@cspell/dict-shell": "^1.0.6",
"ajv-cli": "^5.0.0",
"markdownlint-cli": "^0.39.0"
},
"browserslist": {
Expand Down
Loading

0 comments on commit 7f28550

Please sign in to comment.