diff --git a/.gitmodules b/.gitmodules new file mode 100644 index 00000000..f9469e9f --- /dev/null +++ b/.gitmodules @@ -0,0 +1,3 @@ +[submodule "external/dev-ocean"] + path = external/dev-ocean + url = https://github.com/oceanprotocol/dev-ocean diff --git a/.prettierignore b/.prettierignore index 93090764..e13e1e09 100644 --- a/.prettierignore +++ b/.prettierignore @@ -1,3 +1,4 @@ node_modules public .cache +external diff --git a/README.md b/README.md index 18473cd2..7aa8cc53 100644 --- a/README.md +++ b/README.md @@ -20,6 +20,7 @@ - [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) @@ -45,12 +46,26 @@ Those sections are defined in the [`/data/sections.yml`](data/sections.yml) file ### Content Files Some content files live in the [`/content`](content/) & [`/data`](data/) folders, and is written using Markdown and YAML. -That content is organized into subfolders corresponding to the sections mentioned above. -The subfolder names, along with the filenames, define the final URL of a given piece of content. + +That content is organized into subfolders corresponding to the sections mentioned above. The subfolder names, along with the filenames, define the final URL of a given piece of content. + The final navigational organization of the content is driven through the sidebar files under [`/data/sidebars`](data/sidebars/). + Some global values used throughout the site can be set in [`config.js`](config.js). -TODO: Additionally, some content files live in other repositories and are pulled into the site at build time, e.g. +#### External Content Files + +Additionally, some content files live in other repositories and are maintained there. They are pulled into the site at build time. + +At the moment, this is setup for the following repositories: + +- [dev-ocean](https://github.com/oceanprotocol/dev-ocean) + +For including a document from any of the above repositories, 4 values are required in a document's YAML frontmatter. If found, a page will be generated automatically, accessible under the defined `slug`. + +This will NOT include this page in the doc's sidebar navigation, this needs to be done manually in the docs repo in one of the sidebar files. This is so you can check out everything before exposing it to visitors, and to ensure editorial workflow of the categorization. + +TODO: In a later stage, we will include more documentation in this site, e.g.: - API references - Component docs @@ -59,27 +74,39 @@ TODO: Additionally, some content files live in other repositories and are pulled ### Markdown File Requirements All Markdown files should use -[GitHub Flavored Markdown](https://help.github.com/articles/about-writing-and-formatting-on-github/) -and must satisfy some extra requirements: +[GitHub Flavored Markdown](https://help.github.com/articles/about-writing-and-formatting-on-github/) and must satisfy some extra requirements: -1. The file must begin with a section that looks like this (YAML): +1. The file must begin with a section called YAML frontmatter that looks like this: - ```text - --- + ```yaml title: This is the Title in Title Case description: A short description of the page. --- Markdown content begins here. ``` - Note: The `description` value will be rendered on-page below the title, and it will also be used for description tags in the HTML header. + For external documents in other repos, defining the `slug` and `section` is required: -1. Don't include the page title or description in the Markdown section. That is, don't begin the Markdown content with `# This is the Title in Title Case`. Just write as if that were already there. -1. Internal links to other docs pages should be: + ```yaml + title: This is the Title in Title Case + description: A short description of the page. + slug: /concepts/architecture/ + section: concepts + --- + Markdown content begins here. + ``` + + Note: The `description` value will be rendered on-page below the title, and it will also be used for description tags in the HTML head. + +2. Don't include the page title or description in the Markdown section. That is, don't begin the Markdown content with `# This is the Title in Title Case`. Just write as if that were already there. +3. start your heading levels with `h2`, so `## My heading` +4. Internal links to other docs pages should be: - to the _full absolute URL_, such as https://docs.oceanprotocol.com/hello/you-are-awesome/ or https://github.com/oceanprotocol/dev-ocean/blob/master/doc/development/style-guides.md or - - to a relative URL that looks like `/concepts/terminology/` with slashes on the beginning and end, and with no `.md` or `.html` at the end (before the last slash). + - to a absolute URL without the host, that looks like `/concepts/terminology/` with slashes on the beginning and end, and with no `.md` or `.html` at the end (before the last slash). +5. no TOC please, this will be generated automatically from all headings +6. for images and media, you can keep them in the original repo. Images will be automatically grabbed by the docs site on querying. When doing that, docs site will generate all sorts of image sizes to handle proper responsive images, so no need to keep an eye on image dimensions or file sizes -Have a look at [docs.oceanprotocol.com/test/](https://docs.oceanprotocol.com/test/) to see what content elements can be used in the docs. +**Have a look at [docs.oceanprotocol.com/test/](https://docs.oceanprotocol.com/test/) to see what content elements can be used in all markdown files included in docs site.** ### Adding Docs @@ -147,7 +174,7 @@ As a prerequisite you'll need on your machine: Clone this repo, install all dependencies, and start the development server: ```bash -git clone git@github.com:oceanprotocol/docs.git +git clone --recursive git@github.com:oceanprotocol/docs.git cd docs/ # add GITHUB_TOKEN diff --git a/config.js b/config.js index fb848472..0b586a03 100644 --- a/config.js +++ b/config.js @@ -14,5 +14,9 @@ module.exports = { twitter: 'https://twitter.com/oceanprotocol', gitter: 'https://gitter.im/oceanprotocol/Lobby', telegram: 'https://t.me/joinchat/GUyxrE0Hi154D0NrlOqLFg' - } + }, + githubContentPath: + 'https://github.com/oceanprotocol/docs/blob/master/content', + githubDevOceanPath: + 'https://github.com/oceanprotocol/dev-ocean/blob/master/doc' } diff --git a/content/concepts/architecture.md b/content/concepts/architecture.md deleted file mode 100644 index 80db458b..00000000 --- a/content/concepts/architecture.md +++ /dev/null @@ -1,10 +0,0 @@ ---- -title: Architecture -description: The architecture of Ocean Protocol with all its components and how they work together. ---- - -See the page about the [Ocean network components](/concepts/components/). - -See the (somewhat-dated) diagram on the page https://github.com/oceanprotocol/dev-ocean/blob/master/doc/architecture.md - -![Ocean Protocol Components](images/components.png 'Ocean Protocol Components') diff --git a/content/concepts/components.md b/content/concepts/components.md index a1237640..17c967e6 100644 --- a/content/concepts/components.md +++ b/content/concepts/components.md @@ -7,11 +7,11 @@ Before reading this page, you should understand some [Ocean-specific terminology ## Aquarius -Every marketplace must run an instance of Aquarius. -Aquarius provides an API to an off-chain database ("OceanDB") to store and manage metadata about data assets: the assets listed in that marketplace. +Aquarius provides an API to an off-chain database ("OceanDB") to store and manage metadata about data assets: the assets listed in that marketplace. Every marketplace must run an instance of Aquarius. + The off-chain database might be MongoDB, Elasticsearch or BigchainDB. - + ## Brizo diff --git a/content/test.md b/content/test.md index abad41e0..b90152d0 100644 --- a/content/test.md +++ b/content/test.md @@ -7,7 +7,7 @@ For more complete info, see [John Gruber's original spec](http://daringfireball. ## Table of Contents -- [Headers](#headers) +- [Headers](#header) - [Emphasis](#emphasis) - [Lists](#lists) - [Links](#links) @@ -20,6 +20,8 @@ For more complete info, see [John Gruber's original spec](http://daringfireball. - [Line Breaks](#line-breaks) - [Videos](#videos) - [React Components in Markdown](#react-components-in-markdown) +- [Repository Component](#repository-component) +- [Embedding File Contents from GitHub](#embedding-file-contents-from-github) ## Headers @@ -113,14 +115,10 @@ Some text to show that the reference links can follow later. Or leave it empty and use the [link text itself] - - URLs and URLs in angle brackets will automatically get turned into links. http://www.example.com or and sometimes example.com (but not on Github, for example). - - Some text to show that the reference links can follow later. [arbitrary case-insensitive reference text]: https://www.mozilla.org @@ -349,20 +347,40 @@ Or, in pure Markdown, but losing the image sizing and border: [![IMAGE ALT TEXT HERE](http://img.youtube.com/vi/YOUTUBE_VIDEO_ID_HERE/0.jpg)](http://www.youtube.com/watch?v=YOUTUBE_VIDEO_ID_HERE) ``` -## React Components in Markdown +### Repository Component In all Markdown docs you can use some select React Components. This magic is done with [gatsby-remark-component](https://www.gatsbyjs.org/packages/gatsby-remark-component/). -Note that the component name in Markdown needs to be always in lowercase, and have a closing tag. - -### Repository - The `Repository` component fetching and displaying information about a GitHub repo. Component can be used in Markdown as ``, it requires a `name` to be passed: -```HTML +```html ``` +Note that the component name in Markdown needs to be always in lowercase, and have a closing tag. + Resulting in: + +You can also pass `readme="true"` and the readme contents of the repo will be rendered: + +```html + +``` + +Resulting in: + + + +## Embedding File Contents from GitHub + +You can embed any file contents like so, note that the language needs to be defined manually to get proper syntax highlighting: + +```text +GITHUB-EMBED https://github.com/oceanprotocol/squid-js/blob/develop/src/keeper/Web3Provider.ts js GITHUB-EMBED +``` + +Resulting in: + +GITHUB-EMBED https://github.com/oceanprotocol/squid-js/blob/develop/src/keeper/Web3Provider.ts js GITHUB-EMBED diff --git a/data/sections.yml b/data/sections.yml index 45faaa4a..af878449 100644 --- a/data/sections.yml +++ b/data/sections.yml @@ -5,7 +5,7 @@ - title: Setup Guides description: Setting up the Ocean Protocol components. - link: /setup/marketplace/ + link: /setup/quickstart/ color: blue - title: Tutorials diff --git a/data/sidebars/concepts.yml b/data/sidebars/concepts.yml index d1452801..36bf9678 100644 --- a/data/sidebars/concepts.yml +++ b/data/sidebars/concepts.yml @@ -6,13 +6,17 @@ link: /concepts/terminology/ - title: Software Components link: /concepts/components/ - - title: Architecture - link: /concepts/architecture/ -- group: Details +- group: Architecture items: - - title: Coming Soon - link: / + - title: Overview + link: /concepts/architecture/ + - title: Squid + link: /concepts/squid/ + - title: Secret Store + link: /concepts/secret-store/ + - title: Computing Services + link: /concepts/computing-services/ - group: Contribute items: diff --git a/gatsby-config.js b/gatsby-config.js index a45c92d8..9f3d7fec 100755 --- a/gatsby-config.js +++ b/gatsby-config.js @@ -37,7 +37,6 @@ module.exports = { path: `${__dirname}/data` } }, - { resolve: 'gatsby-source-filesystem', options: { @@ -45,6 +44,13 @@ module.exports = { path: `${__dirname}/node_modules/@oceanprotocol/art` } }, + { + resolve: 'gatsby-source-filesystem', + options: { + name: 'dev-ocean', + path: `${__dirname}/external/dev-ocean/doc` + } + }, { resolve: 'gatsby-source-graphql', options: { @@ -73,6 +79,17 @@ module.exports = { showCaptions: true } }, + { + resolve: 'gatsby-remark-github', + options: { + marker: 'GITHUB-EMBED', + insertEllipsisComments: true, + ellipsisPhrase: '...', + useCache: true, + cacheKey: 'gatsby-remark-github-v1', + token: process.env.GITHUB_TOKEN + } + }, 'gatsby-remark-smartypants', 'gatsby-remark-embed-video', 'gatsby-remark-responsive-iframe', diff --git a/gatsby-node.js b/gatsby-node.js index 8930d691..9dcdeddb 100755 --- a/gatsby-node.js +++ b/gatsby-node.js @@ -7,8 +7,17 @@ exports.onCreateNode = ({ node, getNode, actions }) => { if (node.internal.type === 'MarkdownRemark') { const fileNode = getNode(node.parent) const parsedFilePath = path.parse(fileNode.relativePath) - const slug = createFilePath({ node, getNode, basePath: 'content' }) - const section = parsedFilePath.dir + + let slug = createFilePath({ node, getNode, basePath: 'content' }) + let section = parsedFilePath.dir + + if (node.frontmatter.slug) { + ;({ slug } = node.frontmatter) + } + + if (node.frontmatter.section) { + ;({ section } = node.frontmatter) + } createNodeField({ node, @@ -44,6 +53,27 @@ exports.createPages = ({ graphql, actions }) => { } } } + + architectureDocs: allMarkdownRemark( + filter: { + fileAbsolutePath: { regex: "/dev-ocean/doc/" } + } + ) { + edges { + node { + fields { + slug + section + } + frontmatter { + slug + title + description + section + } + } + } + } } ` ).then(result => { @@ -53,8 +83,8 @@ exports.createPages = ({ graphql, actions }) => { reject(result.errors) } - const posts = result.data.allMarkdownRemark.edges const docTemplate = path.resolve('./src/templates/Doc.jsx') + const posts = result.data.allMarkdownRemark.edges // Create Doc pages posts.forEach(post => { @@ -68,6 +98,29 @@ exports.createPages = ({ graphql, actions }) => { }) }) + // Create Architecture section from dev-ocean contents + const postsArchitecture = result.data.architectureDocs.edges + + postsArchitecture + // only grab files with required frontmatter defined + .filter( + post => + post.node.frontmatter.slug && + post.node.frontmatter.title && + post.node.frontmatter.description && + post.node.frontmatter.section + ) + .forEach(post => { + createPage({ + path: `${post.node.fields.slug}`, + component: docTemplate, + context: { + slug: post.node.fields.slug, + section: post.node.fields.section + } + }) + }) + resolve() }) ) diff --git a/package.json b/package.json index 6149bda7..66811ff1 100755 --- a/package.json +++ b/package.json @@ -15,7 +15,7 @@ "format": "run-p format:js format:css format:md format:yml", "lint:js": "eslint --ignore-path .gitignore --ignore-path .prettierignore --ext .js,.jsx .", "lint:css": "stylelint './src/**/*.{css,scss}'", - "lint:md": "markdownlint './**/*.{md,markdown}' --ignore node_modules", + "lint:md": "markdownlint './**/*.{md,markdown}' --ignore './{node_modules,external,public}/**/*'", "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" @@ -23,13 +23,13 @@ "dependencies": { "@oceanprotocol/art": "^1.0.2", "classnames": "^2.2.6", - "gatsby": "^2.0.45", + "gatsby": "^2.0.50", "gatsby-image": "^2.0.20", "gatsby-plugin-catch-links": "^2.0.8", "gatsby-plugin-google-analytics": "^2.0.7", - "gatsby-plugin-manifest": "^2.0.8", - "gatsby-plugin-offline": "^2.0.13", - "gatsby-plugin-react-helmet": "^3.0.1", + "gatsby-plugin-manifest": "^2.0.9", + "gatsby-plugin-offline": "^2.0.15", + "gatsby-plugin-react-helmet": "^3.0.2", "gatsby-plugin-sass": "^2.0.4", "gatsby-plugin-sharp": "^2.0.12", "gatsby-plugin-sitemap": "^2.0.2", @@ -38,6 +38,7 @@ "gatsby-remark-component": "^1.1.3", "gatsby-remark-copy-linked-files": "^2.0.6", "gatsby-remark-embed-video": "^1.4.0", + "gatsby-remark-github": "^1.0.1", "gatsby-remark-images": "^2.0.6", "gatsby-remark-prismjs": "^3.0.3", "gatsby-remark-responsive-iframe": "^2.0.6", @@ -51,13 +52,15 @@ "intersection-observer": "^0.5.1", "node-sass": "^4.10.0", "prismjs": "^1.15.0", - "react": "^16.6.1", - "react-dom": "^16.6.1", + "react": "^16.6.3", + "react-dom": "^16.6.3", "react-helmet": "^5.2.0", - "rehype-react": "^3.0.3" + "rehype-react": "^3.0.3", + "remark": "^10.0.0", + "remark-react": "^4.0.3" }, "devDependencies": { - "@svgr/webpack": "^4.0.2", + "@svgr/webpack": "^4.0.3", "dotenv": "^6.1.0", "eslint": "^5.9.0", "eslint-config-oceanprotocol": "^1.3.0", diff --git a/src/components/DocFooter.jsx b/src/components/DocFooter.jsx index 3aa32086..fe2eedf3 100644 --- a/src/components/DocFooter.jsx +++ b/src/components/DocFooter.jsx @@ -2,20 +2,39 @@ import React from 'react' import PropTypes from 'prop-types' import { ReactComponent as Pencil } from '../images/pencil.svg' import styles from './DocFooter.module.scss' +import { githubContentPath, githubDevOceanPath } from '../../config' -const githubContentPath = - 'https://github.com/oceanprotocol/docs/blob/master/content' +const DocFooter = ({ post }) => { + const { sourceInstanceName } = post.parent -const DocFooter = ({ post }) => ( - -) + let path + let externalRepoName + + switch (sourceInstanceName) { + case 'dev-ocean': + path = githubDevOceanPath + externalRepoName = sourceInstanceName + break + default: + path = githubContentPath + } + + return ( + + ) +} DocFooter.propTypes = { post: PropTypes.object.isRequired diff --git a/src/components/DocFooter.module.scss b/src/components/DocFooter.module.scss index d567bb69..b9e5b331 100644 --- a/src/components/DocFooter.module.scss +++ b/src/components/DocFooter.module.scss @@ -30,3 +30,11 @@ .active { color: $brand-pink !important; // stylelint-disable-line declaration-no-important } + +.externalRepoName { + font-family: $font-family-monospace; + font-weight: $font-weight-base; + font-size: $font-size-mini; + text-transform: none; + margin-left: $spacer / 4; +} diff --git a/src/components/DocToc.jsx b/src/components/DocToc.jsx new file mode 100644 index 00000000..e67158ac --- /dev/null +++ b/src/components/DocToc.jsx @@ -0,0 +1,16 @@ +import React from 'react' +import PropTypes from 'prop-types' +import styles from './DocToc.module.scss' + +const DocToc = ({ tableOfContents }) => ( +