From 91a75374ea89526296a49c97f0b305a221513a36 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" Date: Fri, 13 Sep 2024 03:18:38 +0000 Subject: [PATCH] [Docs] Creates Developer docs GH page code (#5977) * Working Dev docs Signed-off-by: Ashwin P Chandran Create CNAME Delete CNAME disable jekyll Signed-off-by: Ashwin P Chandran change to relative path Signed-off-by: Ashwin P Chandran add docs readme Signed-off-by: Ashwin P Chandran Adds changelog Signed-off-by: Ashwin P Chandran * removes unnecessary debugger Signed-off-by: Ashwin P Chandran --------- Signed-off-by: Ashwin P Chandran (cherry picked from commit 3aa0e5aefa35a581b67def1bd510a4e8ab5c49bd) Signed-off-by: github-actions[bot] --- .nojekyll | 0 docs/DOCS_README.md | 15 +++ docs/_sidebar.md | 177 +++++++++++++++++++++++++++++++ docs/index.html | 39 +++++++ index.html | 13 +++ package.json | 1 + scripts/generate_docs_sidebar.js | 141 ++++++++++++++++++++++++ 7 files changed, 386 insertions(+) create mode 100644 .nojekyll create mode 100644 docs/DOCS_README.md create mode 100644 docs/_sidebar.md create mode 100644 docs/index.html create mode 100644 index.html create mode 100644 scripts/generate_docs_sidebar.js diff --git a/.nojekyll b/.nojekyll new file mode 100644 index 00000000000..e69de29bb2d diff --git a/docs/DOCS_README.md b/docs/DOCS_README.md new file mode 100644 index 00000000000..96ae397fdf6 --- /dev/null +++ b/docs/DOCS_README.md @@ -0,0 +1,15 @@ +# Welcome to the Developer Guide + +Welcome to our Developer Guide! This site is dedicated to providing comprehensive documentation to support developers using OpenSearch Dashboards. Here, you'll find a quick way to access all the readme's that exist within the OpenSearch Dashboards repo in an easy to find manner. + +## About This Documentation + +The documentation is dynamically generated using [Docsify](https://docsify.js.org/). Docsify dynamically renders the Markdown files into HTML pages without the need for a build step. Docsify uses the documentation directly from the repository. The links in the sidebar are generated based on the folder structure of the repository. To update the links in the sidebar, run `yarn docs:generateDevDocs`. + +## Starting Up the Doc Site Locally + +To start up the documentation site locally for development or validation purposes, you can simply start a server in the root directory of the repository. `npx serve` is a simple way to start a server. + +--- + +[Repo Readme](../README.md) diff --git a/docs/_sidebar.md b/docs/_sidebar.md new file mode 100644 index 00000000000..db1e0a09b57 --- /dev/null +++ b/docs/_sidebar.md @@ -0,0 +1,177 @@ +* [Home](/) + + - Capabilities + - [Read_only_mode](capabilities/read_only_mode.md) + - Charts + - [Current_usage](charts/current_usage.md) + - Docker dev + - [Docker dev setup manual](docker-dev/docker-dev-setup-manual.md) + - Multi datasource + - [Client_management_design](multi-datasource/client_management_design.md) + - [High_level_design](multi-datasource/high_level_design.md) + - [User_stories](multi-datasource/user_stories.md) + - Plugins + - [Data_persistence](plugins/data_persistence.md) + - Saved_objects + - [Saved_object_repository_factory_design](saved_objects/saved_object_repository_factory_design.md) + - src + - [Core](../src/core/README.md) + - dev + - [Build](../src/dev/build/README.md) + - [I18n](../src/dev/i18n/README.md) + - plugins + - [Bfetch](../src/plugins/bfetch/README.md) + - [Charts](../src/plugins/charts/README.md) + - console + - public + - application + - [Hooks](../src/plugins/console/public/application/hooks/README.md) + - [Dashboard](../src/plugins/dashboard/README.md) + - [Data](../src/plugins/data/README.md) + - [Data_explorer](../src/plugins/data_explorer/README.md) + - [Data_source](../src/plugins/data_source/README.md) + - [Data_source_management](../src/plugins/data_source_management/README.md) + - [Dev_tools](../src/plugins/dev_tools/README.md) + - [Discover](../src/plugins/discover/README.md) + - [Embeddable](../src/plugins/embeddable/README.md) + - [Expressions](../src/plugins/expressions/README.md) + - [Home](../src/plugins/home/README.md) + - index_pattern_management + - public + - components + - create_index_pattern_wizard + - [CREATE_INDEX_PATTERN](../src/plugins/index_pattern_management/public/components/create_index_pattern_wizard/CREATE_INDEX_PATTERN.md) + - [Input_control_vis](../src/plugins/input_control_vis/README.md) + - [Inspector](../src/plugins/inspector/README.md) + - [Navigation](../src/plugins/navigation/README.md) + - [Opensearch_dashboards_legacy](../src/plugins/opensearch_dashboards_legacy/README.md) + - [Opensearch_dashboards_overview](../src/plugins/opensearch_dashboards_overview/README.md) + - [Opensearch_dashboards_react](../src/plugins/opensearch_dashboards_react/README.md) + - [Opensearch_dashboards_usage_collection](../src/plugins/opensearch_dashboards_usage_collection/README.md) + - [Opensearch_dashboards_utils](../src/plugins/opensearch_dashboards_utils/README.md) + - opensearch_ui_shared + - public + - forms + - [Form_wizard](../src/plugins/opensearch_ui_shared/public/forms/form_wizard/README.md) + - [Multi_content](../src/plugins/opensearch_ui_shared/public/forms/multi_content/README.md) + - [Saved_objects](../src/plugins/saved_objects/README.md) + - [Saved_objects_management](../src/plugins/saved_objects_management/README.md) + - [Share](../src/plugins/share/README.md) + - [Telemetry](../src/plugins/telemetry/README.md) + - [Telemetry_collection_manager](../src/plugins/telemetry_collection_manager/README.md) + - [Telemetry_management_section](../src/plugins/telemetry_management_section/README.md) + - [Ui_actions](../src/plugins/ui_actions/README.md) + - [Url_forwarding](../src/plugins/url_forwarding/README.md) + - [Usage_collection](../src/plugins/usage_collection/README.md) + - [Vis_augmenter](../src/plugins/vis_augmenter/README.md) + - [Vis_builder](../src/plugins/vis_builder/README.md) + - [Vis_default_editor](../src/plugins/vis_default_editor/README.md) + - [Vis_type_markdown](../src/plugins/vis_type_markdown/README.md) + - [Vis_type_metric](../src/plugins/vis_type_metric/README.md) + - [Vis_type_table](../src/plugins/vis_type_table/README.md) + - [Vis_type_tagcloud](../src/plugins/vis_type_tagcloud/README.md) + - [Vis_type_timeline](../src/plugins/vis_type_timeline/README.md) + - [Vis_type_timeseries](../src/plugins/vis_type_timeseries/README.md) + - [Vis_type_vega](../src/plugins/vis_type_vega/README.md) + - [Vis_type_vislib](../src/plugins/vis_type_vislib/README.md) + - [Vis_type_xy](../src/plugins/vis_type_xy/README.md) + - [Visualizations](../src/plugins/visualizations/README.md) + - [Visualize](../src/plugins/visualize/README.md) + - examples + - [Dashboard_embeddable_examples](../examples/dashboard_embeddable_examples/README.md) + - [Developer_examples](../examples/developer_examples/README.md) + - embeddable_examples + - public + - [Todo](../examples/embeddable_examples/public/todo/README.md) + - [Expressions_example](../examples/expressions_example/README.md) + - [Routing_example](../examples/routing_example/README.md) + - [Search_examples](../examples/search_examples/README.md) + - [Ui_action_examples](../examples/ui_action_examples/README.md) + - [Ui_actions_explorer](../examples/ui_actions_explorer/README.md) + - [Url_generators_examples](../examples/url_generators_examples/README.md) + - [Url_generators_explorer](../examples/url_generators_explorer/README.md) + - packages + - [Opensearch datemath](../packages/opensearch-datemath/readme.md) + - [Opensearch eslint config opensearch dashboards](../packages/opensearch-eslint-config-opensearch-dashboards/README.md) + - [Opensearch safer lodash set](../packages/opensearch-safer-lodash-set/README.md) + - [Osd ace](../packages/osd-ace/README.md) + - [Osd apm config loader](../packages/osd-apm-config-loader/README.md) + - [Osd babel preset](../packages/osd-babel-preset/README.md) + - [Osd config](../packages/osd-config/README.md) + - [Osd config schema](../packages/osd-config-schema/README.md) + - [Osd cross platform](../packages/osd-cross-platform/README.md) + - [Osd dev utils](../packages/osd-dev-utils/README.md) + - [Osd eslint import resolver opensearch dashboards](../packages/osd-eslint-import-resolver-opensearch-dashboards/README.md) + - [Osd eslint plugin eslint](../packages/osd-eslint-plugin-eslint/README.md) + - [Osd expect](../packages/osd-expect/README.md) + - [Osd i18n](../packages/osd-i18n/README.md) + - [Osd logging](../packages/osd-logging/README.md) + - [Osd monaco](../packages/osd-monaco/README.md) + - [Osd opensearch](../packages/osd-opensearch/README.md) + - [Osd optimizer](../packages/osd-optimizer/README.md) + - [Osd plugin generator](../packages/osd-plugin-generator/README.md) + - [Osd plugin helpers](../packages/osd-plugin-helpers/README.md) + - [Osd pm](../packages/osd-pm/README.md) + - [Osd spec to console](../packages/osd-spec-to-console/README.md) + - [Osd std](../packages/osd-std/README.md) + - [Osd stylelint config](../packages/osd-stylelint-config/README.md) + - [Osd stylelint plugin stylelint](../packages/osd-stylelint-plugin-stylelint/README.md) + - [Osd telemetry tools](../packages/osd-telemetry-tools/README.md) + - [Osd test](../packages/osd-test/README.md) + - [Osd test subj selector](../packages/osd-test-subj-selector/README.md) + - [Osd ui framework](../packages/osd-ui-framework/README.md) + - [Osd ui shared deps](../packages/osd-ui-shared-deps/README.md) + - [Osd utility types](../packages/osd-utility-types/README.md) + - [Osd utils](../packages/osd-utils/README.md) + - [README](../packages/README.md) + - release-notes + - [Opensearch dashboards.release notes 1.0.0 rc1](../release-notes/opensearch-dashboards.release-notes-1.0.0-rc1.md) + - [Opensearch dashboards.release notes 1.0.0](../release-notes/opensearch-dashboards.release-notes-1.0.0.md) + - [Opensearch dashboards.release notes 1.1.0](../release-notes/opensearch-dashboards.release-notes-1.1.0.md) + - [Opensearch dashboards.release notes 1.2.0](../release-notes/opensearch-dashboards.release-notes-1.2.0.md) + - [Opensearch dashboards.release notes 1.3.0](../release-notes/opensearch-dashboards.release-notes-1.3.0.md) + - [Opensearch dashboards.release notes 1.3.1](../release-notes/opensearch-dashboards.release-notes-1.3.1.md) + - [Opensearch dashboards.release notes 1.3.10](../release-notes/opensearch-dashboards.release-notes-1.3.10.md) + - [Opensearch dashboards.release notes 1.3.11](../release-notes/opensearch-dashboards.release-notes-1.3.11.md) + - [Opensearch dashboards.release notes 1.3.12](../release-notes/opensearch-dashboards.release-notes-1.3.12.md) + - [Opensearch dashboards.release notes 1.3.13](../release-notes/opensearch-dashboards.release-notes-1.3.13.md) + - [Opensearch dashboards.release notes 1.3.14](../release-notes/opensearch-dashboards.release-notes-1.3.14.md) + - [Opensearch dashboards.release notes 1.3.2](../release-notes/opensearch-dashboards.release-notes-1.3.2.md) + - [Opensearch dashboards.release notes 1.3.3](../release-notes/opensearch-dashboards.release-notes-1.3.3.md) + - [Opensearch dashboards.release notes 1.3.5](../release-notes/opensearch-dashboards.release-notes-1.3.5.md) + - [Opensearch dashboards.release notes 1.3.6](../release-notes/opensearch-dashboards.release-notes-1.3.6.md) + - [Opensearch dashboards.release notes 1.3.7](../release-notes/opensearch-dashboards.release-notes-1.3.7.md) + - [Opensearch dashboards.release notes 1.3.8](../release-notes/opensearch-dashboards.release-notes-1.3.8.md) + - [Opensearch dashboards.release notes 1.3.9](../release-notes/opensearch-dashboards.release-notes-1.3.9.md) + - [Opensearch dashboards.release notes 2.0.0 rc1](../release-notes/opensearch-dashboards.release-notes-2.0.0-rc1.md) + - [Opensearch dashboards.release notes 2.0.0](../release-notes/opensearch-dashboards.release-notes-2.0.0.md) + - [Opensearch dashboards.release notes 2.0.1](../release-notes/opensearch-dashboards.release-notes-2.0.1.md) + - [Opensearch dashboards.release notes 2.1.0](../release-notes/opensearch-dashboards.release-notes-2.1.0.md) + - [Opensearch dashboards.release notes 2.10.0](../release-notes/opensearch-dashboards.release-notes-2.10.0.md) + - [Opensearch dashboards.release notes 2.11.0](../release-notes/opensearch-dashboards.release-notes-2.11.0.md) + - [Opensearch dashboards.release notes 2.11.1](../release-notes/opensearch-dashboards.release-notes-2.11.1.md) + - [Opensearch dashboards.release notes 2.12.0](../release-notes/opensearch-dashboards.release-notes-2.12.0.md) + - [Opensearch dashboards.release notes 2.2.0](../release-notes/opensearch-dashboards.release-notes-2.2.0.md) + - [Opensearch dashboards.release notes 2.2.1](../release-notes/opensearch-dashboards.release-notes-2.2.1.md) + - [Opensearch dashboards.release notes 2.3.0](../release-notes/opensearch-dashboards.release-notes-2.3.0.md) + - [Opensearch dashboards.release notes 2.4.0](../release-notes/opensearch-dashboards.release-notes-2.4.0.md) + - [Opensearch dashboards.release notes 2.4.1](../release-notes/opensearch-dashboards.release-notes-2.4.1.md) + - [Opensearch dashboards.release notes 2.5.0](../release-notes/opensearch-dashboards.release-notes-2.5.0.md) + - [Opensearch dashboards.release notes 2.6.0](../release-notes/opensearch-dashboards.release-notes-2.6.0.md) + - [Opensearch dashboards.release notes 2.7.0](../release-notes/opensearch-dashboards.release-notes-2.7.0.md) + - [Opensearch dashboards.release notes 2.8.0](../release-notes/opensearch-dashboards.release-notes-2.8.0.md) + - [Opensearch dashboards.release notes 2.9.0](../release-notes/opensearch-dashboards.release-notes-2.9.0.md) + - scripts + - [README](../scripts/README.md) + - [DOCS_README](DOCS_README.md) + - [CHANGELOG](../CHANGELOG.md) + - [CODE_OF_CONDUCT](../CODE_OF_CONDUCT.md) + - [COMMUNICATIONS](../COMMUNICATIONS.md) + - [CONTRIBUTING](../CONTRIBUTING.md) + - [DEVELOPER_GUIDE](../DEVELOPER_GUIDE.md) + - [MAINTAINERS](../MAINTAINERS.md) + - [README](../README.md) + - [RELEASING](../RELEASING.md) + - [SECURITY](../SECURITY.md) + - [TESTING](../TESTING.md) + - [TYPESCRIPT](../TYPESCRIPT.md) diff --git a/docs/index.html b/docs/index.html new file mode 100644 index 00000000000..ba48d832860 --- /dev/null +++ b/docs/index.html @@ -0,0 +1,39 @@ + + + + + Document + + + + + + + + + +
+ + + + + + + + + diff --git a/index.html b/index.html new file mode 100644 index 00000000000..9b141ed8f1e --- /dev/null +++ b/index.html @@ -0,0 +1,13 @@ + + + + + Redirecting... + + + +

If you are not redirected, click here to view the documentation.

+ + diff --git a/package.json b/package.json index cd063f542fd..b3d0c29fdb4 100644 --- a/package.json +++ b/package.json @@ -74,6 +74,7 @@ "osd:watch": "scripts/use_node scripts/opensearch_dashboards --dev --logging.json=false", "build:types": "scripts/use_node scripts/remove.js ./target/types && tsc --p tsconfig.types.json", "docs:acceptApiChanges": "scripts/use_node --max-old-space-size=6144 scripts/check_published_api_changes.js --accept", + "docs:generateDevDocs": "scripts/use_node scripts/generate_docs_sidebar.js", "osd:bootstrap": "scripts/use_node scripts/build_ts_refs && scripts/use_node scripts/register_git_hook", "spec_to_console": "scripts/use_node scripts/spec_to_console", "pkg-version": "scripts/use_node -e \"console.log(require('./package.json').version)\"", diff --git a/scripts/generate_docs_sidebar.js b/scripts/generate_docs_sidebar.js new file mode 100644 index 00000000000..e336441827f --- /dev/null +++ b/scripts/generate_docs_sidebar.js @@ -0,0 +1,141 @@ +/* + * Copyright OpenSearch Contributors + * SPDX-License-Identifier: Apache-2.0 + */ +/* eslint-disable no-restricted-syntax */ + +const fs = require('fs'); +const path = require('path'); + +const startDirs = [ + { + dir: './docs', // Base directory + root: true, // Indicates that this is the base directory + }, + './src', + './examples', + './packages', + './release-notes', + './scripts', + + { + dir: './', + recursively: false, // Do not search recursively from the root directory + root: true, + }, +]; // Directories to start the search from + +const sidebarFile = './docs/_sidebar.md'; // Location to save the generated sidebar +const excludeDirs = ['node_modules', '.git']; // Directories to exclude from the search + +// Function to recursively find Markdown files and return a nested structure +function findMarkdownFiles(dir, prefix = '', baseDir = '', recursively = true) { + const results = []; + const entries = fs.readdirSync(dir, { withFileTypes: true }); + + entries.forEach((entry) => { + if (entry.isDirectory() && !excludeDirs.includes(entry.name) && recursively) { + const nestedResults = findMarkdownFiles( + path.join(dir, entry.name), + `${prefix}${entry.name}/`, + baseDir, + recursively + ); + + if (nestedResults.length > 0) { + // If there is a readme in the directory, use that as the reference for the directory. + const readmeIndex = nestedResults.findIndex( + (item) => item.name.toLowerCase() === 'readme.md' + ); + + if (readmeIndex !== -1) { + const readme = nestedResults.splice(readmeIndex, 1)[0]; + results.push({ + type: 'directory', + name: entry.name, + children: [nestedResults], + readme: readme, + baseDir, + }); + } else { + results.push({ type: 'directory', name: entry.name, children: nestedResults }); + } + } + } else if (entry.name.endsWith('.md') && entry.name !== '_sidebar.md') { + const docPath = `${prefix}${entry.name}`; + // Adjust the path based on its base directory ('docs' or 'src') + const linkPath = + baseDir === 'docs' ? docPath : `../${baseDir ? baseDir + '/' : ''}${docPath}`; + results.push({ type: 'file', name: entry.name, path: linkPath.replace(/\\/g, '/') }); // Ensure path format is consistent + } + }); + + return results; +} + +// Function to generate sidebar content from the nested structure +function generateSidebarContent(items, nestLevel = 0) { + let content = nestLevel === 0 ? '* [Home](/)\n\n' : ''; + + // folders first, then files + items = items.sort((a, b) => { + if (a.type === 'directory' && b.type === 'file') return -1; + }); + + items.forEach((item) => { + if (item.type === 'directory') { + // If there is a readme in the directory, use that as the reference for the directory. + if (item.readme) { + const linkLabel = item.name + .replace(/-/g, ' ') + .replace(/\.md$/, '') + .replace(/^\w/, (c) => c.toUpperCase()); + content += `${' '.repeat(nestLevel)} - [${linkLabel}](${item.readme.path})\n`; + } else { + content += `${' '.repeat(nestLevel)} - ${item.name}\n`; + } + content += generateSidebarContent(item.children, nestLevel + 1); + } else if (item.type === 'file') { + const linkLabel = item.name + .replace(/-/g, ' ') + .replace(/\.md$/, '') + .replace(/^\w/, (c) => c.toUpperCase()); + content += `${' '.repeat(nestLevel)} - [${linkLabel}](${item.path})\n`; + } + }); + + return content; +} + +// Adjust the main function call to include the base directory as a parameter +function generateSidebar() { + let allItems = []; + startDirs.forEach((directory) => { + let { dir, recursively, root } = directory; + if (typeof directory === 'string') { + recursively = true; + root = false; + dir = directory; + } + + const dirItems = findMarkdownFiles(dir, '', dir.slice(2), recursively); // Remove './' and pass the base directory + if (dirItems.length > 0 && !root) { + allItems.push({ type: 'directory', name: dir.slice(2), children: dirItems }); + } else { + allItems = allItems.concat( + findMarkdownFiles(dir, '', dir.slice(2), recursively).map((item) => ({ + ...item, + name: item.name + .replace(/-/g, ' ') + .replace(/\.md$/, '') + .replace(/^\w/, (c) => c.toUpperCase()), + })) + ); // Remove './' and pass the base directory + } + }); + const sidebarContent = generateSidebarContent(allItems); + fs.writeFileSync(sidebarFile, sidebarContent); + console.log('Sidebar generated successfully.'); +} + +generateSidebar();