oceanprotocol/docs
1
0
Fork 0
mirror of https://github.com/oceanprotocol/docs.git synced 2024-07-01 06:02:10 +02:00
Code Releases Activity

Merge pull request #15 from oceanprotocol/feature/github-repo-contents

Browse Source 
Content from GitHub repos
This commit is contained in:
Matthias Kretschmann 2018-11-16 10:40:59 +01:00 committed by GitHub
commit 3f6aef64ff
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
23 changed files with 354 additions and 82 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

3
.gitmodules vendored Normal file
View File

@ -0,0 +1,3 @@
[submodule "external/dev-ocean"]
path = external/dev-ocean
url = https://github.com/oceanprotocol/dev-ocean

1
.prettierignore
View File

@ -1,3 +1,4 @@
node_modules
public
.cache
external

55
README.md
View File

@ -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

6
config.js
View File

@ -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'
}

10
content/concepts/architecture.md
View File

@ -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')

6
content/concepts/components.md
View File

@ -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.
<repo name="aquarius"></repo>
<repo name="aquarius" readme="true"></repo>
## Brizo

40
content/test.md
View File

@ -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]
<!-- markdownlint-disable no-bare-urls -->
URLs and URLs in angle brackets will automatically get turned into links.
http://www.example.com or <http://www.example.com> and sometimes
example.com (but not on Github, for example).
<!-- markdownlint-enable no-bare-urls -->
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 `<repo>`, it requires a `name` to be passed:
```HTML
```html
<repo name="pleuston"></repo>
```
Note that the component name in Markdown needs to be always in lowercase, and have a closing tag.
Resulting in:
<repo name="pleuston"></repo>
You can also pass `readme="true"` and the readme contents of the repo will be rendered:
```html
<repo name="aquarius" readme="true"></repo>
```
Resulting in:
<repo name="aquarius" readme="true"></repo>
## 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

2
data/sections.yml
View File

@ -5,7 +5,7 @@
- title: Setup Guides
description: Setting up the Ocean Protocol components.
link: /setup/marketplace/
link: /setup/quickstart/
color: blue
- title: Tutorials

14
data/sidebars/concepts.yml
View File

@ -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:

1
external/dev-ocean vendored Submodule

@ -0,0 +1 @@
Subproject commit 6bbf269da9eaf75c0fd42bd2a71944af52db6f04

19
gatsby-config.js
View File

@ -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',

59
gatsby-node.js
View File

@ -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()
})
)

21
package.json
View File

@ -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",

43
src/components/DocFooter.jsx
View File

@ -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 }) => (
<footer className={styles.footer}>
<a
href={`${githubContentPath}/${post.parent.relativePath}`}
className={!post.html ? styles.active : null}
>
<Pencil /> Edit this page on GitHub
</a>
</footer>
)
let path
let externalRepoName
switch (sourceInstanceName) {
case 'dev-ocean':
path = githubDevOceanPath
externalRepoName = sourceInstanceName
break
default:
path = githubContentPath
}
return (
<footer className={styles.footer}>
<a
href={`${path}/${post.parent.relativePath}`}
className={!post.html ? styles.active : null}
>
<Pencil /> Edit this page on GitHub
{externalRepoName && (
<span className={styles.externalRepoName}>
{externalRepoName}
</span>
)}
</a>
</footer>
)
}
DocFooter.propTypes = {
post: PropTypes.object.isRequired

8
src/components/DocFooter.module.scss
View File

@ -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;
}

16
src/components/DocToc.jsx Normal file
View File

@ -0,0 +1,16 @@
import React from 'react'
import PropTypes from 'prop-types'
import styles from './DocToc.module.scss'
const DocToc = ({ tableOfContents }) => (
<aside
className={styles.toc}
dangerouslySetInnerHTML={{ __html: tableOfContents }}
/>
)
DocToc.propTypes = {
tableOfContents: PropTypes.string.isRequired
}
export default DocToc

11
src/components/DocToc.module.scss Normal file
View File

@ -0,0 +1,11 @@
@import 'variables';
.toc {
background: darken($brand-white, 2%);
padding: $spacer;
margin-bottom: $spacer * 2;
ul {
margin: 0;
}
}

2
src/components/HeaderSection.jsx
View File

@ -18,7 +18,7 @@ const HeaderSection = ({ title }) => (
)
HeaderSection.propTypes = {
title: PropTypes.array
title: PropTypes.PropTypes.oneOfType([PropTypes.array, PropTypes.string])
}
export default HeaderSection

41
src/components/Repositories/Repository.jsx
View File

@ -1,6 +1,8 @@
import React from 'react'
import PropTypes from 'prop-types'
import { StaticQuery, graphql } from 'gatsby'
import remark from 'remark'
import remarkReact from 'remark-react'
import { ReactComponent as Star } from '../../images/star.svg'
import { ReactComponent as Forks } from '../../images/forks.svg'
import styles from './Repository.module.scss'
@ -31,6 +33,12 @@ const queryGithub = graphql`
}
}
}
object(expression: "develop:README.md") {
id
... on GitHub_Blob {
text
}
}
}
}
}
@ -98,7 +106,24 @@ Numbers.propTypes = {
url: PropTypes.string.isRequired
}
const Repository = ({ name, links }) => (
const Readme = ({ object }) => {
const readmeHtml =
object &&
remark()
.use(remarkReact)
.processSync(object.text).contents
return (
object && (
<aside className={styles.repositoryReadme}>
<h3 className={styles.repositoryReadmeTitle}>README.md</h3>
{readmeHtml}
</aside>
)
)
}
const Repository = ({ name, links, readme }) => (
<StaticQuery
query={queryGithub}
render={data => {
@ -119,7 +144,14 @@ const Repository = ({ name, links }) => (
// e.g. when private repos are referenced in repositories.yml
if (repo === undefined) return null
const { url, description, forkCount, stargazers, releases } = repo
const {
url,
description,
forkCount,
stargazers,
releases,
object
} = repo
return (
<article className={styles.repository}>
@ -135,6 +167,8 @@ const Repository = ({ name, links }) => (
url={url}
/>
</footer>
{readme && <Readme object={object} />}
</article>
)
}}
@ -143,7 +177,8 @@ const Repository = ({ name, links }) => (
Repository.propTypes = {
name: PropTypes.string.isRequired,
links: PropTypes.array
links: PropTypes.array,
readme: PropTypes.oneOfType([PropTypes.bool, PropTypes.string])
}
export default Repository

29
src/components/Repositories/Repository.module.scss
View File

@ -87,3 +87,32 @@
margin-bottom: -.1rem;
}
}
.repositoryReadme {
margin-top: $spacer / $line-height;
padding: $spacer / 2;
background: darken($brand-white, 2%);
h1,
h2 {
font-size: $font-size-large;
}
h3,
h4 {
font-size: $font-size-base;
}
img {
display: inline-block;
}
}
.repositoryReadmeTitle {
font-size: $font-size-small !important; // stylelint-disable-line
font-family: $font-family-monospace;
font-weight: $font-weight-base;
margin: 0;
color: $brand-grey-light;
margin-bottom: $spacer / 2;
}

20
src/styles/global.scss
View File

@ -102,6 +102,12 @@ ol {
color: $brand-grey-light;
user-select: none;
}
ul,
ol,
p {
margin-bottom: 0;
}
}
}
@ -247,15 +253,23 @@ samp {
// lots of !important to overwrite prims.js theme
font-family: $font-family-monospace !important;
font-size: $font-size-small !important;
background: $brand-black !important;
color: $brand-grey-lighter !important;
border-radius: $border-radius !important;
text-shadow: none !important;
}
:not(pre) > code {
background: darken($brand-white, 5%) !important;
color: $brand-grey-dark !important;
display: inline-block;
padding-left: .3rem !important;
padding-right: .3rem !important;
}
pre {
display: block;
margin-bottom: $spacer !important;
padding: 0 !important;
background: $brand-black !important;
// make 'em scrollable
overflow: auto;
@ -265,7 +279,7 @@ pre {
padding: $spacer;
white-space: pre;
display: block;
color: inherit;
color: $brand-grey-lighter !important;
overflow-wrap: normal;
word-wrap: normal;
word-break: normal;

18
src/templates/Doc.jsx
View File

@ -6,6 +6,7 @@ import Layout from '../components/Layout'
import Content from '../components/Content'
import HeaderSection from '../components/HeaderSection'
import Sidebar from '../components/Sidebar'
import DocToc from '../components/DocToc'
import DocContent from '../components/DocContent'
import DocHeader from '../components/DocHeader'
import DocFooter from '../components/DocFooter'
@ -23,6 +24,7 @@ export default class DocTemplate extends Component {
const sections = this.props.data.allSectionsYaml.edges
const { section } = post.fields
const { title, description } = post.frontmatter
const { tableOfContents } = post
// output section title as defined in sections.yml
const sectionTitle = sections.map(({ node }) => {
@ -56,6 +58,13 @@ export default class DocTemplate extends Component {
title={title}
description={description}
/>
{tableOfContents && (
<DocToc
tableOfContents={tableOfContents}
/>
)}
<DocContent
html={post.html}
htmlAst={post.htmlAst}
@ -69,6 +78,11 @@ export default class DocTemplate extends Component {
title={title}
description={description}
/>
{tableOfContents && (
<DocToc tableOfContents={tableOfContents} />
)}
<DocContent
html={post.html}
htmlAst={post.htmlAst}
@ -87,10 +101,9 @@ export const pageQuery = graphql`
query DocBySlug($slug: String!) {
markdownRemark(fields: { slug: { eq: $slug } }) {
id
excerpt
tableOfContents
html
htmlAst
fileAbsolutePath
frontmatter {
title
description
@ -116,6 +129,7 @@ export const pageQuery = graphql`
parent {
... on File {
relativePath
sourceInstanceName
}
}
}

11
src/templates/Doc.module.scss
View File

@ -7,12 +7,17 @@
}
.sidebar {
flex: 0 0 27%;
margin-top: $spacer / 2;
margin-bottom: $spacer / 2;
top: $spacer;
+ .main {
flex: 0 0 73%;
@media (min-width: $break-point--medium) {
width: 27%;
margin-bottom: 0;
+ .main {
width: 73%;
}
}
}