WIP: draft TODO. Simplify code.

Author: jstirnaman

api-docs/scripts/generate-openapi-articles.js

@@ -18,45 +18,42 @@ const execCommand = (command) => {
 };
 
 // Function to generate data from OpenAPI
-function generateDataFromOpenAPI(specFile, dataOutPath, articleOutPath) {
-  if (!fs.existsSync(dataOutPath)) {
-    fs.mkdirSync(dataOutPath, { recursive: true });
+function generateApiData(specFile, dataPath) {
+  if (!fs.existsSync(dataPath)) {
+    fs.mkdirSync(dataPath, { recursive: true });
   }
 
   openapiDocs.openapiToData({
-    dataOutPath,
-    articleOutPath,
-    specFile
+    specFile,
+    dataPath
   });
 };
 
 // Example usage of generateDataFromOpenAPI function
 // generateDataFromOpenAPI('path/to/openapi-file.yml', 'path/to/paths-output-folder', 'path/to/metadata-output-folder');
 
-const generatePagesFromArticleData = async (articlesPath, contentPath) => {
+const generateApiPages = async (dataPath, contentPath) => {
   let config = {
     root: '.', //Root hugo folder, can be empty
-    dataFolder: articlesPath, //Data folder path (will fetch ALL files from here)
+    dataFolder: dataPath, //Data folder path (will fetch ALL files from here)
     type: "api", //Type name [basically layout] (save it under "layouts/NAME/single.html" or themes/THEME/layouts/NAME/single.html). Can be overridden on individual pages by defining "type" under "fields"
-    pages: "articles", //Pages element in your data, in case it's "posts" or "articles" etc.
+    pages: "paths", //Pages element in your data, in case it's "posts" or "articles" etc.
     contentPath: contentPath, //Path to content directory (in case it's not "content")
     hugoPath: `${DOCS_ROOT}/node_modules/.bin/hugo-extended` //Path to hugo binary (if global, e.g. /snap/bin/hugo)
   }
   configJson = `'${JSON.stringify(config)}'`;
-  console.log('Clean...')
-  execCommand(
-    `node ./node_modules/hugo-data-to-pages/hugo.js clean --force --config=${configJson}`
-  )
+  // console.log('Clean...')
+  // execCommand(
+  //   `node ./node_modules/hugo-data-to-pages/hugo.js clean --force --config=${configJson}`
+  // )
   console.log('Generate...')
   execCommand(
     `node ./node_modules/hugo-data-to-pages/hugo.js generate --config=${configJson}`
   )
 }
 
-// To output to a public folder where JavaScript can access it, use /static/<namespace>--for example: /static/openapi/
 const config = {
-  dataOutPath: path.join(DOCS_ROOT, '/data/api/influxdb'),
-  metadataOutPath: path.join(DOCS_ROOT, `/data/api-metadata/influxdb`),
+  dataDir: path.join(DOCS_ROOT, '/data/api/influxdb'),
   apis: [
     {
       name: 'cloud-v2',
@@ -74,12 +71,19 @@ const config = {
 config.apis.forEach(api => {
   // Execute the getswagger.sh script
   execCommand(`${path.join(DOCS_ROOT, '/api-docs/getswagger.sh')} ${api.name} -B`);
-  const dataOut = path.join(config.dataOutPath, api.name);
-  const metadataOut = path.join(config.metadataOutPath, api.name);
-  if (!fs.existsSync(dataOut)) {
-    fs.mkdirSync(dataOut, { recursive: true });
+  // Copy the generated spec to /data
+  const specDataDir = path.join(config.dataDir, api.name);
+  if (!fs.existsSync(specDataDir)) {
+    fs.mkdirSync(specDataDir, { recursive: true });
   }
-  fs.copyFileSync(api.spec_file, path.join(dataOut, api.name + '.yml'));
-  generateDataFromOpenAPI(api.spec_file, dataOut, metadataOut);
-  generatePagesFromArticleData(metadataOut, api.pages_dir);
+  const specDataFile = path.join(specDataDir, api.name + '.yml');
+  fs.copyFileSync(api.spec_file, specDataFile);
+  const apiPathsDir = path.join(specDataDir, '/paths');
+  generateApiData(api.spec_file, apiPathsDir);
+  
+  // Remove old pages
+  fs.rmSync(api.pages_dir, {recursive: true, force: true});
+  // generateDataFromOpenAPI(api.spec_file, dataOut, metadataOut);
+  fs.mkdirSync(api.pages_dir, { recursive: true });
+  generateApiPages(apiPathsDir, api.pages_dir);
 });

api-docs/scripts/openapi-docs/index.js

@@ -18,7 +18,7 @@ const openapiUtils = {
   }
 }
 
-function openapiPaths(openapi, prefix, outPath) {
+function openapiPaths(openapi, outPath) {
   const pathGroups = {};
   Object.keys(openapi.paths).sort()
   .forEach((p) => {
@@ -49,7 +49,7 @@ function openapiPaths(openapi, prefix, outPath) {
       if (!fs.existsSync(outPath)) {
         fs.mkdirSync(outPath, {recursive: true});
       }
-      const realOutPath = path.resolve(outPath, `${prefix}${pg.replaceAll('/', '-').replace(/^-/, '')}.yaml`);
+      const realOutPath = path.resolve(outPath, `${pg.replaceAll('/', '-').replace(/^-/, '')}.yaml`);
       writeDataFile(doc, realOutPath);
     } catch (err) {
       console.error(err);
@@ -117,14 +117,10 @@ function openapiMetadata(sourcePath, targetPath, opts) {
 }
 
 function openapiToData(options) {
-  const filenamePrefix = `${path.parse(options.specFile).name}-`;
-
   const sourceFile = readFile(options.specFile, 'utf8');
-  console.log(`Generating OpenAPI path files in ${options.dataOutPath}....`);
-  openapiPaths(sourceFile, filenamePrefix, options.dataOutPath);
-
-  console.log(`Generating OpenAPI article data in ${options.articleOutPath}...`);
-  openapiMetadata(options.dataOutPath, options.articleOutPath, {filePattern: filenamePrefix});
+  console.log(`Generating OpenAPI path files in ${options.dataPath}....`);
+  openapiPaths(sourceFile, options.dataPath);
+  //openapiMetadata(options.dataPath);
 }
 
 module.exports = {

content/api-ref-pipeline-notes.md

@@ -0,0 +1,25 @@
+# API reference pipeline with Hugo
+
+- Hugo can render the following content formats as page content:
+  Markdown, HTML, Emacs Org Mode, AsciiDoc, Pandoc, or reStructuredText.
+
+- Front matter at the top of each content file is metadata that:
+
+  - Describes the content
+  - Augments the content
+  - Establishes relationships with other content
+  - Controls the published structure of your site
+  - Determines template selection
+
+1. Create a content type (folder) or assign a `type` property for API reference (OpenAPI) paths. For example, if the page structure is `content/influxdb/v2/api/v2/[OpenAPI path]`, then add `type: api_path` to the frontmatter and, if necessary, specify a layout: `layout: api_path`.
+1. Store each product's OpenAPI spec files in YAML format inside a "namespaced" (to avoid collisions) directory structure in `/data`.
+1. For each product.path, generate a page with all path metadata in the frontmatter. See [`.Site.Data`](https://gohugo.io/methods/site/data/)
+2. Create a template to render the path
+3. Create additional templates that process page data for nav, filtering, links, code samples, etc.
+
+
+
+## Useful functions 
+
+- [`data.GetJSON`](https://gohugo.io/functions/data/getjson/): Returns a JSON object from a local or remote JSON file, or an error if the file does not exist.
+- [`resources.GetRemote URL`](https://gohugo.io/functions/resources/getremote/): fetches and caches remote resources (images, js, etc.)

layouts/_default/api.html

@@ -3,6 +3,16 @@
 {{ partial "header.html" . }}
 {{ partial "topnav.html" . }}
 
+{{ range $category, $api := .Site.Data.api.influxdb.v2_cloud.cloud_v2 }}
+  <p>{{ $category | title }}</p>
+  <ul>
+    {{ range $api }}
+      <li>{{ .info.title }}<br /> ({{ .info.description }})</li>
+    {{ end }}
+  </ul>
+{{ end }}
+
+<!--Rapidoc demo
 <div class="page-wrapper">
   {{ partial "sidebar.html" . }}
   <div class="content-wrapper">
@@ -35,5 +45,5 @@ <h2>{{ .Params.title }}</h2>
     <div class="copyright">© {{ now.Year }} InfluxData, Inc.</div>
   </div>
 </div>
-
+-->
 {{ partial "footer.html" . }}