Merge pull request #656 from oceanprotocol/feature/read-the-docs

Feature/read the docs

data/sidebars/references.yml

@@ -47,3 +47,8 @@
   items:
     - title: API Reference
       link: https://github.com/oceanprotocol/provider-py
+
+- group: Ocean Subgraph
+  items:
+    - title: Readme References
+      link: /read-the-docs/ocean-subgraph/

gatsby-node.js

@@ -73,6 +73,7 @@ exports.createPages = ({ graphql, actions }) => {
                     title
                     app
                     module
+                    version
                   }
                 }
               }
@@ -133,7 +134,10 @@ exports.createPages = ({ graphql, actions }) => {
         // API: ocean.js
         const lastRelease =
           result.data.oceanJs.repository.releases.edges.filter(
-            ({ node }) => !node.isPrerelease && !node.isDraft
+            ({ node }) =>
+              !node.isPrerelease &&
+              !node.isDraft &&
+              node.releaseAssets.edges.length > 0
           )[0].node.releaseAssets.edges[0].node
 
         await createTypeDocPage(
@@ -159,10 +163,12 @@ exports.createPages = ({ graphql, actions }) => {
         const oceanPyList = filterMarkdownList(markdowns, 'ocean.py')
         const aquariusList = filterMarkdownList(markdowns, 'aquarius')
         const providerList = filterMarkdownList(markdowns, 'provider')
+        const subgraphList = filterMarkdownList(markdowns, 'ocean-subgraph')
 
         await createReadTheDocsPage(createPage, 'ocean-py', oceanPyList)
         await createReadTheDocsPage(createPage, 'aquarius', aquariusList)
         await createReadTheDocsPage(createPage, 'provider', providerList)
+        await createReadTheDocsPage(createPage, 'ocean-subgraph', subgraphList)
 
         resolve()
       })
@@ -184,39 +190,7 @@ const createTypeDocPage = async (createPage, name, downloadUrl) => {
       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/Account',
-          'ocean/Assets',
-          'ocean/Compute',
-          'ocean/Versions',
-          'ocean/DID',
-          'ddo/DDO',
-          'metadatacache/MetadataCache',
-          'metadatacache/OnChainMetaDataCache',
-          'provider/Provider',
-          'datatokens/Datatokens',
-          'datatokens/Network',
-          'datatokens/Web3Provider',
-          'balancer/OceanPool',
-          'balancer/Pool',
-          'balancer/PoolFactory',
-          'exchange/FixedRateExchange',
-          'models/Config',
-          'utils/ConfigHelper',
-          'utils/GasUtils',
-          'ocean/utils/OceanUtils',
-          'ocean/utils/WebServiceConnector',
-          'utils/Logger'
-        ]
+        typedoc: await typedoc.json()
       }
     })
   } catch (error) {

src/templates/ContentWrapperTemplate.jsx

@@ -0,0 +1,80 @@
+import React, { Component } from 'react'
+import PropTypes from 'prop-types'
+import { Helmet } from 'react-helmet'
+import Layout from '../components/Layout'
+import Content from '../components/Content'
+import HeaderSection from '../components/HeaderSection'
+import Sidebar from '../components/Sidebar'
+import DocHeader from '../components/DocHeader'
+import Seo from '../components/Seo'
+
+import stylesDoc from './Doc.module.scss'
+
+export default class ContentWrapperTemplate extends Component {
+  static propTypes = {
+    data: PropTypes.object.isRequired,
+    location: PropTypes.object.isRequired,
+    slug: PropTypes.string.isRequired,
+    toc: PropTypes.object.isRequired,
+    info: PropTypes.object.isRequired,
+    children: PropTypes.any
+  }
+
+  sectionTitle = this.props.data.allSectionsYaml.edges.map(({ node }) => {
+    if (node.title.toLowerCase().includes('references')) {
+      return node.title
+    }
+  })
+
+  render() {
+    const { location } = this.props
+    const { title, description, version } = this.props.info
+
+    return (
+      <>
+        <Helmet>
+          <body className="references" />
+        </Helmet>
+
+        <Seo
+          title={title}
+          description={description}
+          slug={this.props.slug}
+          article
+          location={location}
+        />
+
+        <Layout location={location}>
+          <HeaderSection title={this.sectionTitle} />
+
+          <Content>
+            <main className={stylesDoc.wrapper}>
+              <aside className={stylesDoc.sidebar}>
+                <Sidebar
+                  location={location}
+                  sidebar="references"
+                  collapsed
+                  toc
+                  tocComponent={this.props.toc}
+                />
+              </aside>
+              <article className={stylesDoc.main}>
+                <DocHeader
+                  title={title}
+                  description={description}
+                  prepend={
+                    <span className={stylesDoc.version}>
+                      <span>v{version}</span>
+                    </span>
+                  }
+                />
+
+                {this.props.children}
+              </article>
+            </main>
+          </Content>
+        </Layout>
+      </>
+    )
+  }
+}

src/templates/Markdown/MarkdownList.jsx

@@ -84,11 +84,6 @@ export default function MarkdownList({ location, pageContext }) {
     <Layout>
       <HeaderSection title={pageContext.name} />
       <Content>
-        <div style={{ color: '#ff8c00' }}>
-          <span>&#9888;</span>
-          This documentation is a work in progess. Please feel free to report
-          any issues.
-        </div>
         <main className={styles.wrapper}>
           <aside className={styles.sidebar}>
             <div className={sidebarStyles.sidebar}>{nestedSidebarList}</div>

src/templates/MarkdownTemplate.jsx

@@ -23,6 +23,7 @@ export default function MarkdownTemplate({ data }) {
           >
             View source on Github
           </a>
+          v{post.frontmatter.version}
         </footer>
       </Content>
     </>

src/templates/Swagger/index.jsx

@@ -1,21 +1,14 @@
-import React, { Component } from 'react'
+import React from 'react'
 import PropTypes from 'prop-types'
 import { graphql } from 'gatsby'
-import { Helmet } from 'react-helmet'
 
-import Layout from '../../components/Layout'
-import Content from '../../components/Content'
-import HeaderSection from '../../components/HeaderSection'
-import Sidebar from '../../components/Sidebar'
-import DocHeader from '../../components/DocHeader'
 import DocFooter from '../../components/DocFooter'
-import Seo from '../../components/Seo'
 
 import Toc from './Toc'
 import Paths from './Paths'
 
-import stylesDoc from '../Doc.module.scss'
 import styles from './index.module.scss'
+import ContentWrapperTemplate from '../ContentWrapperTemplate'
 
 const SwaggerMeta = ({ contact, license }) => (
   <ul className={styles.swaggerMeta}>
@@ -52,87 +45,52 @@ BasePath.propTypes = {
   basePath: PropTypes.string
 }
 
-export default class ApiSwaggerTemplate extends Component {
-  static propTypes = {
-    data: PropTypes.object.isRequired,
-    location: PropTypes.object.isRequired,
-    pageContext: PropTypes.object.isRequired
-  }
+export default function ApiSwaggerTemplate({
+  data,
+  path,
+  location,
+  pageContext
+}) {
+  const { api } = pageContext
+  const { host, basePath, info, paths } = api
+  const { title, license, contact } = info
 
-  // output section title as defined in sections.yml
-  sectionTitle = this.props.data.allSectionsYaml.edges.map(({ node }) => {
-    // compare section against section title from sections.yml
-    if (node.title.toLowerCase().includes('references')) {
-      return node.title
-    }
-  })
+  return (
+    <>
+      <ContentWrapperTemplate
+        data={data}
+        path={path}
+        location={location}
+        slug={pageContext.slug}
+        info={info}
+        toc={<Toc data={api} />}
+      >
+        {(contact || license) && (
+          <SwaggerMeta contact={contact} license={license} />
+        )}
 
-  render() {
-    const { location, pageContext } = this.props
-    const { api } = pageContext
-    const { host, basePath, info, paths } = api
-    const { title, description, version, license, contact } = info
+        {(host || basePath) && <BasePath host={host} basePath={basePath} />}
 
-    return (
-      <>
-        <Helmet>
-          <body className="references" />
-        </Helmet>
+        <Paths paths={paths} />
 
-        <Seo
-          title={title}
-          description={description}
-          slug={pageContext.slug}
-          article
-          location={location}
+        <DocFooter
+          url={`https://github.com/oceanprotocol/${title.toLowerCase()}`}
+          externalName={`${title} Swagger spec`}
         />
+      </ContentWrapperTemplate>
+    </>
+  )
+}
 
-        <Layout location={location}>
-          <HeaderSection title={this.sectionTitle} />
-
-          <Content>
-            <main className={stylesDoc.wrapper}>
-              <aside className={stylesDoc.sidebar}>
-                <Sidebar
-                  location={location}
-                  sidebar="references"
-                  collapsed
-                  toc
-                  tocComponent={<Toc data={api} />}
-                />
-              </aside>
-              <article className={stylesDoc.main}>
-                <DocHeader
-                  title={title}
-                  description={description}
-                  prepend={
-                    <span className={stylesDoc.version}>
-                      <span>v{version}</span>
-                    </span>
-                  }
-                />
-
-                {(contact || license) && (
-                  <SwaggerMeta contact={contact} license={license} />
-                )}
-
-                {(host || basePath) && (
-                  <BasePath host={host} basePath={basePath} />
-                )}
-
-                <Paths paths={paths} />
-
-                <DocFooter
-                  url={`https://github.com/oceanprotocol/${title.toLowerCase()}`}
-                  externalName={`${title} Swagger spec`}
-                />
-              </article>
-            </main>
-          </Content>
-        </Layout>
-      </>
-    )
-  }
+ApiSwaggerTemplate.propTypes = {
+  pageContext: PropTypes.shape({
+    slug: PropTypes.string.isRequired,
+    api: PropTypes.object.isRequired,
+    name: PropTypes.string.isRequired
+  }),
+  location: PropTypes.object.isRequired,
+  data: PropTypes.object.isRequired,
+  path: PropTypes.string.isRequired
 }
 
 export const apiSwaggerQuery = graphql`

src/templates/Typedoc/Entities.jsx

@@ -1,10 +1,9 @@
 import React from 'react'
 import PropTypes from 'prop-types'
 import slugify from 'slugify'
-import shortid from 'shortid'
 import Scroll from '../../components/Scroll'
 import styles from './Entities.module.scss'
-import { filterByKindOfProperty } from './utils'
+import shortid from 'shortid'
 
 const Type = ({ type }) => {
   let isArray = false
@@ -33,7 +32,7 @@ const Type = ({ type }) => {
             {typeArguments.map((typeArgument, i) => (
               <span key={shortid.generate()}>
                 {i !== 0 && <span className={styles.typeSymbol}>, </span>}
-                <Type type={typeArgument} />
+                {typeArgument.name}
               </span>
             ))}
           </span>
@@ -50,19 +49,6 @@ Type.propTypes = {
   type: PropTypes.object.isRequired
 }
 
-const PropertyDetails = ({ property }) => {
-  const { type } = property
-  return (
-    <div>
-      <Type type={type} />
-    </div>
-  )
-}
-
-PropertyDetails.propTypes = {
-  property: PropTypes.object
-}
-
 const MethodDetails = ({ property }) => {
   const signature = property.signatures[0]
   const { parameters, type } = signature
@@ -78,7 +64,7 @@ const MethodDetails = ({ property }) => {
             const description = comment && (comment.text || comment.shortText)
 
             return (
-              <div className={styles.parameters} key={shortid.generate()}>
+              <div className={styles.parameters} key={name}>
                 <h5>
                   <code>{name}</code>
                   {isOptional && (
@@ -114,12 +100,18 @@ MethodDetails.propTypes = {
   property: PropTypes.object
 }
 
+const getSourceLink = (sources, sourceUrl) => {
+  return sources && sources[0]
+    ? `${sourceUrl}src/${sources[0].fileName}#L${sources[0].line}`
+    : ''
+}
+
 const PropertyWrapper = ({ property, sourceUrl, parentAnchor }) => {
   const { name, kindString, flags, signatures, sources, decorators } = property
   const { isPublic, isStatic } = flags
   const signature = signatures && signatures[0]
-  const comment = (signature && signature.comment) || property.comment
-  const { fileName, line } = sources[0]
+  const comment = signature?.comment || property.comment
+
   const deprecation = (decorators || []).filter(
     ({ name }) => name === 'deprecated'
   )[0] // Assuming deprecated annotation
@@ -129,7 +121,7 @@ const PropertyWrapper = ({ property, sourceUrl, parentAnchor }) => {
     deprecatedSlug = deprecatedUse && slugify(deprecatedUse.replace('.', '-'))
   }
 
-  const sourceLink = `${sourceUrl}${fileName}#L${line}`
+  const sourceLink = getSourceLink(sources, sourceUrl)
 
   return (
     <div
@@ -175,18 +167,22 @@ const PropertyWrapper = ({ property, sourceUrl, parentAnchor }) => {
             case 'Method':
               return <MethodDetails property={property} />
             case 'Property':
-              return <PropertyDetails property={property} />
+              return (
+                <div>
+                  <Type type={property} />
+                </div>
+              )
           }
         })()}
 
-      {fileName && (
+      {sources && sources[0] && (
         <a
           className={styles.sourceLink}
           href={sourceLink}
           target="_blank"
           rel="noopener noreferrer"
         >
-          {`${fileName}#L${line}`}
+          {`src/${sources[0].fileName}#L${sources[0].line}`}
         </a>
       )}
     </div>
@@ -199,9 +195,9 @@ PropertyWrapper.propTypes = {
   parentAnchor: PropTypes.string
 }
 
-const Entities = ({ entities, sourceUrl }) =>
-  entities.map(({ name, comment, children }) => (
-    <div key={shortid.generate()} id={name && slugify(name)}>
+const Entities = ({ entities, sourceUrl }) => {
+  return entities.map(({ name, comment, children }) => (
+    <div key={name} id={name && slugify(name)}>
       <h2 className={styles.entityName}>
         <code>{name}</code>
       </h2>
@@ -213,19 +209,17 @@ const Entities = ({ entities, sourceUrl }) =>
       )}
 
       {children &&
-        children
-          .filter(filterByKindOfProperty)
-          .map((property) => (
-            <PropertyWrapper
-              key={shortid.generate()}
-              property={property}
-              sourceUrl={sourceUrl}
-              parentAnchor={name && slugify(name)}
-            />
-          ))}
+        children.map((property) => (
+          <PropertyWrapper
+            key={property.id}
+            property={property}
+            sourceUrl={sourceUrl}
+            parentAnchor={name && slugify(name)}
+          />
+        ))}
     </div>
   ))
-
+}
 Entities.propTypes = {
   entities: PropTypes.array.isRequired,
   sourceUrl: PropTypes.string

src/templates/Typedoc/Toc.jsx

@@ -4,7 +4,6 @@ import slugify from 'slugify'
 import shortid from 'shortid'
 import Scrollspy from 'react-scrollspy'
 import Scroll from '../../components/Scroll'
-import { filterByKindOfProperty } from './utils'
 import stylesSidebar from '../../components/Sidebar.module.scss'
 
 export default class Toc extends PureComponent {
@@ -14,13 +13,13 @@ export default class Toc extends PureComponent {
 
   subItems = (children, parentName) =>
     children &&
-    children.filter(filterByKindOfProperty).map(({ name, decorators }) => {
+    children.map(({ name, decorators }) => {
       const deprecation = (decorators || []).filter(
         ({ name }) => name === 'deprecated'
       )[0] // Assuming deprecated annotation
 
       return (
-        <li key={shortid.generate()}>
+        <li key={name}>
           <Scroll
             type="id"
             element={`${parentName}-${name && slugify(name)}`}
@@ -39,7 +38,7 @@ export default class Toc extends PureComponent {
 
     subIds.push(
       children &&
-        children.filter(filterByKindOfProperty).map(({ name }) => {
+        children.map(({ name }) => {
           return `${parentName}-${name && slugify(name)}`
         })
     )

src/templates/Typedoc/index.jsx

@@ -1,92 +1,40 @@
-import React, { Component } from 'react'
-import PropTypes from 'prop-types'
+import React from 'react'
 import { graphql } from 'gatsby'
-import { Helmet } from 'react-helmet'
-import Layout from '../../components/Layout'
-import Content from '../../components/Content'
-import HeaderSection from '../../components/HeaderSection'
-import Sidebar from '../../components/Sidebar'
-import DocHeader from '../../components/DocHeader'
-import Seo from '../../components/Seo'
-import { cleanTypedocData } from './utils'
+import PropTypes from 'prop-types'
 
 import Entities from './Entities'
 import Toc from './Toc'
 
-import stylesDoc from '../Doc.module.scss'
+import ContentWrapperTemplate from '../ContentWrapperTemplate'
 
-export default class TypedocTemplate extends Component {
-  static propTypes = {
-    data: PropTypes.object.isRequired,
-    location: PropTypes.object.isRequired,
-    pageContext: PropTypes.object.isRequired
-  }
+export default function TypedocTemplate({ data, path, location, pageContext }) {
+  const { typedoc } = pageContext
+  const { sourceUrl } = typedoc.info
 
-  typedocCleaned = cleanTypedocData(
-    this.props.pageContext.typedoc,
-    this.props.pageContext.classes
+  return (
+    <>
+      <ContentWrapperTemplate
+        data={data}
+        path={path}
+        location={location}
+        slug={pageContext.slug}
+        info={typedoc.info}
+        toc={<Toc data={typedoc.children} />}
+      >
+        <Entities entities={typedoc.children} sourceUrl={sourceUrl} />
+      </ContentWrapperTemplate>
+    </>
   )
+}
 
-  // output section title as defined in sections.yml
-  sectionTitle = this.props.data.allSectionsYaml.edges.map(({ node }) => {
-    // compare section against section title from sections.yml
-    if (node.title.toLowerCase().includes('references')) {
-      return node.title
-    }
-  })
-
-  render() {
-    const { location, pageContext } = this.props
-    const { typedoc } = pageContext
-    const { info } = typedoc
-    const { title, description, version, sourceUrl } = info
-
-    return (
-      <>
-        <Helmet>
-          <body className="references" />
-        </Helmet>
-
-        <Seo
-          title={title}
-          description={description}
-          slug={pageContext.slug}
-          article
-          location={location}
-        />
-
-        <Layout location={location}>
-          <HeaderSection title={this.sectionTitle} />
-
-          <Content>
-            <main className={stylesDoc.wrapper}>
-              <aside className={stylesDoc.sidebar}>
-                <Sidebar
-                  location={location}
-                  sidebar="references"
-                  collapsed
-                  toc
-                  tocComponent={<Toc data={this.typedocCleaned} />}
-                />
-              </aside>
-              <article className={stylesDoc.main}>
-                <DocHeader
-                  title={title}
-                  description={description}
-                  prepend={<span className={stylesDoc.version}>{version}</span>}
-                />
-
-                <Entities
-                  entities={this.typedocCleaned}
-                  sourceUrl={sourceUrl}
-                />
-              </article>
-            </main>
-          </Content>
-        </Layout>
-      </>
-    )
-  }
+TypedocTemplate.propTypes = {
+  data: PropTypes.object.isRequired,
+  path: PropTypes.string.isRequired,
+  pageContext: PropTypes.shape({
+    slug: PropTypes.string.isRequired,
+    typedoc: PropTypes.object.isRequired
+  }),
+  location: PropTypes.object.isRequired
 }
 
 export const TypedocQuery = graphql`

src/templates/Typedoc/utils.js

@@ -1,44 +0,0 @@
-export const cleanTypedocData = (data, useClasses) => {
-  const nodes = data.children
-
-  const cleanData = nodes
-    .map((node) => {
-      const child =
-        node.children &&
-        node.children.filter(({ kindString }) => kindString === 'Class')[0]
-
-      return {
-        ...node,
-        name: node.name.replace(/"/g, '').replace('src/', ''),
-        child
-      }
-    })
-    .filter(({ name }) => (useClasses || []).includes(name))
-    .sort((a, b) => useClasses.indexOf(a.name) - useClasses.indexOf(b.name))
-    .map(({ child }) => child)
-    .map((node) => ({
-      ...node,
-      children:
-        node && node.children && node.children.sort((a, b) => a.id - b.id)
-    }))
-
-  return cleanData
-}
-
-// more kinds: 'Property', 'Enumeration'
-const showKindOfProperty = {
-  Method: { onlyPublic: true },
-  Property: { onlyPublic: true }
-}
-
-export const filterByKindOfProperty = ({ kindString, flags }) => {
-  const config = showKindOfProperty[kindString]
-  if (!config) return
-
-  // filter out static methods by default
-  if (flags.isStatic) return
-
-  if (config.onlyPublic && !flags.isPublic) return
-
-  return true
-}