diff --git a/.eslintrc b/.eslintrc index c38f65cd..587d1261 100644 --- a/.eslintrc +++ b/.eslintrc @@ -10,5 +10,6 @@ "plugins": ["prettier"], "rules": { "prettier/prettier": "error" - } + }, + "env": { "browser": true } } diff --git a/.gitignore b/.gitignore index 4f88c408..adeedae8 100644 --- a/.gitignore +++ b/.gitignore @@ -7,4 +7,3 @@ yarn-error.log .DS_Store .env .env.* -data/squid-js.json diff --git a/.gitmodules b/.gitmodules index cf63a225..e4e9225c 100644 --- a/.gitmodules +++ b/.gitmodules @@ -2,6 +2,3 @@ path = external/dev-ocean url = https://github.com/oceanprotocol/dev-ocean branch = master -[submodule "external/squid-js"] - path = external/squid-js - url = https://github.com/oceanprotocol/squid-js.git diff --git a/README.md b/README.md index 3ebbf2d3..823244a5 100644 --- a/README.md +++ b/README.md @@ -18,29 +18,29 @@ --- -- [Content](#content) - - [Content Files](#content-files) - - [External Content Files](#external-content-files) - - [Markdown File Requirements](#markdown-file-requirements) - - [Adding Docs](#adding-docs) - - [Editing Docs](#editing-docs) - - [Repositories](#repositories) - - [Add Links to a Repository](#add-links-to-a-repository) - - [Release Versions](#release-versions) - - [API References](#api-references) - - [Swagger specs](#swagger-specs) - - [TypeDoc specs](#typedoc-specs) -- [Development](#development) - - [Using npm](#using-npm) - - [Using Docker](#using-docker) -- [Linting & Formatting](#linting--formatting) - - [Editor Setup: VS Code](#editor-setup-vs-code) -- [GitHub Data Fetching](#github-data-fetching) - - [GitHub GraphQL API](#github-graphql-api) - - [GitHub REST API](#github-rest-api) -- [Deployment](#deployment) -- [Authors](#authors) -- [License](#license) +- [Content](#Content) + - [Content Files](#Content-Files) + - [External Content Files](#External-Content-Files) + - [Markdown File Requirements](#Markdown-File-Requirements) + - [Adding Docs](#Adding-Docs) + - [Editing Docs](#Editing-Docs) + - [Repositories](#Repositories) + - [Add Links to a Repository](#Add-Links-to-a-Repository) + - [Release Versions](#Release-Versions) + - [API References](#API-References) + - [Swagger specs](#Swagger-specs) + - [TypeDoc specs](#TypeDoc-specs) +- [Development](#Development) + - [Using npm](#Using-npm) + - [Using Docker](#Using-Docker) +- [Linting & Formatting](#Linting--Formatting) + - [Editor Setup: VS Code](#Editor-Setup-VS-Code) +- [GitHub Data Fetching](#GitHub-Data-Fetching) + - [GitHub GraphQL API](#GitHub-GraphQL-API) + - [GitHub REST API](#GitHub-REST-API) +- [Deployment](#Deployment) +- [Authors](#Authors) +- [License](#License) ## Content @@ -206,11 +206,7 @@ They are fetched and updated automatically upon every site build. For more infor #### TypeDoc specs -Reference pages based on generated `json` file from TypeDoc. TypeScript-based projects are included as git submodules under `./external`. - -On site build, TypeDoc will automatically generate the required `json` spec file into `./data/squid-js.json` and create pages from it. The data from these json files is then used by the TypeDoc template. - -To update the specs to the most recent version, the `./external/squid-js` submodule needs to be manuall updated. That's it, on next site build a new spec will be used. +Reference pages based on generated `json` file from TypeDoc. On every site build, the spec files are fetched from GitHub release artifacts and pages are created from it. The data from these json files is then used by the TypeDoc template. ## Development diff --git a/external/squid-js b/external/squid-js deleted file mode 160000 index 49786785..00000000 --- a/external/squid-js +++ /dev/null @@ -1 +0,0 @@ -Subproject commit 497867854eff2c040934b7fd350383d6f16eefd2 diff --git a/gatsby-node.js b/gatsby-node.js index 638f5a6e..59e8087a 100755 --- a/gatsby-node.js +++ b/gatsby-node.js @@ -78,6 +78,38 @@ exports.createPages = ({ graphql, actions }) => { } } } + + squidJs: github { + repository( + name: "squid-js" + owner: "oceanprotocol" + ) { + name + releases( + first: 1 + orderBy: { + field: CREATED_AT + direction: DESC + } + ) { + edges { + node { + releaseAssets( + first: 1 + name: "squid-js.json" + ) { + edges { + node { + name + downloadUrl + } + } + } + } + } + } + } + } } ` ).then(async result => { @@ -129,141 +161,17 @@ exports.createPages = ({ graphql, actions }) => { }) }) - // - // Create pages from swagger json files - // - const swaggerComponents = ['aquarius', 'brizo'] - const apiSwaggerTemplate = path.resolve( - './src/templates/Swagger/index.jsx' + // API: brizo, aquarius + await createSwaggerPages(createPage) + + // API: squid-js + await createTypeDocPage( + createPage, + result.data.squidJs.repository.name, + result.data.squidJs.repository.releases.edges[0].node + .releaseAssets.edges[0].node.downloadUrl ) - // https://github.com/swagger-api/swagger-js - const fetchSwaggerSpec = async name => { - try { - const client = await Swagger( - `https://nginx-${name}.dev-ocean.com/spec` - ) - return client.spec // The resolved spec - - // client.originalSpec // In case you need it - // client.errors // Any resolver errors - - // Tags interface - // client.apis.pet.addPet({id: 1, name: "bobby"}).then(...) - - // TryItOut Executor, with the `spec` already provided - // client.execute({operationId: 'addPet', parameters: {id: 1, name: "bobby") }).then(...) - } catch (error) { - console.log(error) - } - } - - const getSlug = name => { - const slug = `/references/${name}/` - return slug - } - - const specAquarius = await fetchSwaggerSpec( - swaggerComponents[0] - ) - const slugAquarius = getSlug(swaggerComponents[0]) - - createPage({ - path: slugAquarius, - component: apiSwaggerTemplate, - context: { - slug: slugAquarius, - name: swaggerComponents[0], - api: specAquarius - } - }) - - const specBrizo = await fetchSwaggerSpec(swaggerComponents[1]) - const slugBrizo = getSlug(swaggerComponents[1]) - - createPage({ - path: slugBrizo, - component: apiSwaggerTemplate, - context: { - slug: slugBrizo, - name: swaggerComponents[1], - api: specBrizo - } - }) - - // Swagger Pet Store example - const petStoreSlug = '/references/petstore/' - - try { - const client = await Swagger( - `http://petstore.swagger.io/v2/swagger.json` - ) - - createPage({ - path: petStoreSlug, - component: apiSwaggerTemplate, - context: { - slug: petStoreSlug, - api: client.spec - } - }) - } catch (error) { - console.log(error) - } - - // - // Create pages from TypeDoc json files - // - const typeDocSpecs = ['./data/squid-js.json'] - const typedocTemplate = path.resolve( - './src/templates/Typedoc/index.jsx' - ) - - typeDocSpecs.forEach(spec => { - const typedoc = require(spec) // eslint-disable-line - - const name = path - .basename(spec) - .split('.json') - .join('') - - const slug = `/references/${name}/` - - createPage({ - path: slug, - component: typedocTemplate, - context: { - slug, - typedoc, - // TODO: defining these classes for inclusion - // needs to be handled somewhere else to keep - // it generic for all TypeDoc specs - classes: [ - 'ocean/Ocean', - 'ocean/OceanAccounts', - 'ocean/OceanAssets', - 'ocean/OceanAgreements', - 'ocean/OceanVersions', - 'ocean/Account', - 'ocean/DID', - 'ocean/ServiceAgreements/ServiceAgreement', - 'ddo/DDO', - 'ddo/Service', - 'aquarius/AquariusProvider', - 'aquarius/Aquarius', - 'aquarius/query/SearchQuery', - 'brizo/BrizoProvider', - 'brizo/Brizo', - 'keeper/Keeper', - 'keeper/Web3Provider', - 'secretstore/SecretStoreProvider', - 'models/Config', - 'models/Balance' - ] - } - }) - }) - // // create redirects // @@ -282,3 +190,135 @@ exports.createPages = ({ graphql, actions }) => { ) }) } + +// +// Create pages from TypeDoc json files +// +const createTypeDocPage = async (createPage, name, downloadUrl) => { + try { + const typedoc = await fetch(downloadUrl) + const typedocTemplate = path.resolve( + './src/templates/Typedoc/index.jsx' + ) + console.log(name) + const slug = `/references/${name}/` + + createPage({ + path: slug, + component: typedocTemplate, + context: { + slug, + typedoc: await typedoc.json(), + // We define the classes here so the data object passed as page context + // is as small as possible. + // Caveat: no live update during development when these values are changed. + // + // TODO: defining these classes for inclusion + // needs to be handled somewhere else to keep + // it generic for all TypeDoc specs + classes: [ + 'ocean/Ocean', + 'ocean/OceanAccounts', + 'ocean/OceanAssets', + 'ocean/OceanAgreements', + 'ocean/OceanVersions', + 'ocean/Account', + 'ocean/DID', + 'ocean/ServiceAgreements/ServiceAgreement', + 'ddo/DDO', + 'ddo/Service', + 'aquarius/AquariusProvider', + 'aquarius/Aquarius', + 'aquarius/query/SearchQuery', + 'brizo/BrizoProvider', + 'brizo/Brizo', + 'keeper/Keeper', + 'keeper/Web3Provider', + 'secretstore/SecretStoreProvider', + 'models/Config', + 'models/Balance' + ] + } + }) + } catch (error) { + console.log(error.message) + } +} + +// +// Create pages from swagger json files +// +// https://github.com/swagger-api/swagger-js +const fetchSwaggerSpec = async name => { + try { + const client = await Swagger(`https://nginx-${name}.dev-ocean.com/spec`) + return client.spec // The resolved spec + + // client.originalSpec // In case you need it + // client.errors // Any resolver errors + + // Tags interface + // client.apis.pet.addPet({id: 1, name: "bobby"}).then(...) + + // TryItOut Executor, with the `spec` already provided + // client.execute({operationId: 'addPet', parameters: {id: 1, name: "bobby") }).then(...) + } catch (error) { + console.log(error) + } +} + +const createSwaggerPages = async createPage => { + const swaggerComponents = ['aquarius', 'brizo'] + const apiSwaggerTemplate = path.resolve('./src/templates/Swagger/index.jsx') + + const getSlug = name => { + const slug = `/references/${name}/` + return slug + } + + const specAquarius = await fetchSwaggerSpec(swaggerComponents[0]) + const slugAquarius = getSlug(swaggerComponents[0]) + + createPage({ + path: slugAquarius, + component: apiSwaggerTemplate, + context: { + slug: slugAquarius, + name: swaggerComponents[0], + api: specAquarius + } + }) + + const specBrizo = await fetchSwaggerSpec(swaggerComponents[1]) + const slugBrizo = getSlug(swaggerComponents[1]) + + createPage({ + path: slugBrizo, + component: apiSwaggerTemplate, + context: { + slug: slugBrizo, + name: swaggerComponents[1], + api: specBrizo + } + }) + + // Swagger Pet Store example + const petStoreSlug = '/references/petstore/' + + try { + const client = await Swagger( + `http://petstore.swagger.io/v2/swagger.json` + ) + + createPage({ + path: petStoreSlug, + component: apiSwaggerTemplate, + context: { + slug: petStoreSlug, + api: client.spec + } + }) + } catch (error) { + console.log(error) + } +} diff --git a/package.json b/package.json index f42e017a..36008faa 100644 --- a/package.json +++ b/package.json @@ -5,8 +5,8 @@ "author": "Ocean Protocol ", "license": "Apache-2.0", "scripts": { - "build": "npm run typedoc && gatsby build", - "start": "npm run typedoc && gatsby develop", + "build": "gatsby build", + "start": "gatsby develop", "ssr": "npm run build && serve -s public/", "format:js": "prettier --write '**/*.{js,jsx}'", "format:css": "prettier-stylelint --write --quiet 'src/**/*.{css,scss}'", @@ -19,8 +19,7 @@ "lint:yml": "prettier '**/*.{yml,yaml}' --list-different", "lint": "run-p --continue-on-error lint:js lint:css lint:md lint:yml", "test": "npm run lint", - "deploy": "./scripts/deploy.sh", - "typedoc": "node ./scripts/typedoc.js" + "deploy": "./scripts/deploy.sh" }, "dependencies": { "@oceanprotocol/art": "^2.2.0", @@ -77,14 +76,12 @@ "markdownlint-cli": "^0.17.0", "node-sass": "^4.12.0", "npm-run-all": "^4.1.5", - "ora": "^3.4.0", "prettier": "^1.18.2", "prettier-stylelint": "^0.4.2", "stylelint": "^10.1.0", "stylelint-config-bigchaindb": "^1.2.2", "stylelint-config-css-modules": "^1.4.0", - "stylelint-config-standard": "^18.3.0", - "typedoc": "^0.14.2" + "stylelint-config-standard": "^18.3.0" }, "repository": { "type": "git", diff --git a/scripts/typedoc.js b/scripts/typedoc.js deleted file mode 100644 index 2d782beb..00000000 --- a/scripts/typedoc.js +++ /dev/null @@ -1,65 +0,0 @@ -#!/usr/bin/env node - -/* eslint-disable no-console, security/detect-child-process, security/detect-non-literal-fs-filename */ - -const fs = require('fs') -const typedoc = require('typedoc') -const typescript = require('typescript') -const ora = require('ora') -const squidJsPackage = require('../external/squid-js/package.json') -const { exec } = require('child_process') - -const { description, version } = squidJsPackage - -// Setup our paths, relative to project root -const outPath = './data/squid-js.json' -const files = ['./external/squid-js/src/squid.ts'] - -// specifically point to tsconfig, otherwise TypeDoc fails -const config = typescript.findConfigFile( - './external/squid-js', - typescript.sys.fileExists -) - -// npm install for squid-js -const spinnerNpm = ora('Installing submodule dependencies...').start() -const install = exec( - 'cd ./external/squid-js && npm i && git checkout package-lock.json' -) - -install.on('exit', () => { - spinnerNpm.succeed('Installed submodule dependencies.') - generateJson() -}) - -const generateJson = () => { - const spinnerTypedoc = ora('Generating TypeDoc json...').start() - - // Setup our TypeDoc app - const app = new typedoc.Application({ - tsconfig: config - }) - - const src = app.expandInputFiles(files) - const project = app.convert(src) - - // Generate the JSON file - app.generateJson(project, outPath) - - // Parse and modify json output - const jsonOrig = JSON.parse(fs.readFileSync(outPath, 'utf8')) - - const jsonFinal = { - info: { - title: 'Squid-js', - description, - version, - sourceUrl: 'https://github.com/oceanprotocol/squid-js/blob/master/' - }, - ...jsonOrig - } - - fs.writeFileSync(outPath, JSON.stringify(jsonFinal, null, 4)) - - spinnerTypedoc.succeed('Generated TypeDoc json.') -}