mirror of
https://github.com/oceanprotocol/docs.git
synced 2024-11-26 19:49:26 +01:00
fetch squid-js typedoc spec from GitHub release
This commit is contained in:
parent
1351837e6a
commit
56779570c9
GPG Key ID:
606EEEF3C479A91F
@ -10,5 +10,6 @@
|
||||
"plugins": ["prettier"],
|
||||
"rules": {
|
||||
"prettier/prettier": "error"
|
||||
}
|
||||
},
|
||||
"env": { "browser": true }
|
||||
}
|
||||
|
||||
1
.gitignore
vendored
1
.gitignore
vendored
@ -7,4 +7,3 @@ yarn-error.log
|
||||
.DS_Store
|
||||
.env
|
||||
.env.*
|
||||
data/squid-js.json
|
||||
|
||||
3
.gitmodules
vendored
3
.gitmodules
vendored
@ -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
|
||||
|
||||
52
README.md
52
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
|
||||
|
||||
|
||||
1
external/squid-js
vendored
1
external/squid-js
vendored
@ -1 +0,0 @@
|
||||
Subproject commit 497867854eff2c040934b7fd350383d6f16eefd2
|
||||
306
gatsby-node.js
306
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)
|
||||
}
|
||||
}
|
||||
|
||||
11
package.json
11
package.json
@ -5,8 +5,8 @@
|
||||
"author": "Ocean Protocol <devops@oceanprotocol.com>",
|
||||
"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",
|
||||
|
||||
@ -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.')
|
||||
}
|
||||
Loading…
Reference in New Issue
Block a user