From 1b26599abd3bbfc92553ab3a9edb81135ce1e0a0 Mon Sep 17 00:00:00 2001 From: Matthias Kretschmann Date: Sun, 11 Nov 2018 04:02:34 +0100 Subject: [PATCH] copy updates --- .env.sample | 2 +- README.md | 45 ++++++++++++++++++++------------ content/concepts/contributing.md | 15 +++++++++++ content/concepts/development.md | 2 ++ content/test.md | 2 +- 5 files changed, 47 insertions(+), 19 deletions(-) diff --git a/.env.sample b/.env.sample index 3b926cd6..15c06a4b 100644 --- a/.env.sample +++ b/.env.sample @@ -1 +1 @@ -GITHUB_TOKEN= +GITHUB_TOKEN=add_your_token_here diff --git a/README.md b/README.md index 80d653ed..7ac65060 100644 --- a/README.md +++ b/README.md @@ -14,10 +14,12 @@ **These docs are meant to be viewed on [docs.oceanprotocol.com](https://docs.oceanprotocol.com). You can still browse them here but links or images might not work in some places.** +**If you want to contribute to those docs, then [read on here](#content).** + --- - [Content](#content) - - [Sections](#sections) + - [Content files](#content-files) - [Editing docs](#editing-docs) - [Adding docs](#adding-docs) - [Repositories](#repositories) @@ -29,22 +31,22 @@ ## Content -All content lives in the [`/content`](content/) & [`/data`](data/) folders utilizing GitHub Flavored Markdown and YAML. Content is organized through subfolders corresponding to the sections mentioned below. Those subfolder names, along with the file name, define the final url of a given piece of content. +The documentation is split in multiple sections whose content lives in this repo: + +- **Core concepts**: high-level explanation of concepts, assumptions, and components +- **Setup**: getting started for various stakeholders and use cases +- **Tutorials**: detailed tutorials + +Those sections are defined in the [`/data/sections.yml`](data/sections.yml) file. + +### Content files + +All content lives in the [`/content`](content/) & [`/data`](data/) folders utilizing GitHub Flavored Markdown and YAML. Content is organized through subfolders corresponding to the sections mentioned above. Those subfolder names, along with the file name, define the final url of a given piece of content. The final navigational organisation 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). Have a look at [docs.oceanprotocol.com/test/](https://docs.oceanprotocol.com/test/) to see what content elements can be used in the docs. -### Sections - -The documentation is split in multiple sections whose content lives in this repo: - -- Core concepts: high-level explanation of concepts, assumptions, and components -- Setup: getting started for various stakeholders and use cases -- Tutorials: detailed tutorials - -Those sections and their copy are defined in the [`/data/sections.yml`](data/sections.yml) file. - TODO: Additionally, these docs live in their respective repos and are pulled into this site on build time: - API references @@ -87,6 +89,12 @@ The above example will result in: screen shot 2018-11-10 at 22 43 41 +This repository component can also be used within any Markdown content like so: + +``` + +``` + Additionally, you can attach multiple links to a repo. The GitHub link is automatically added for every repository and will always be displayed. Add more links like so: ```yaml @@ -113,10 +121,16 @@ Clone this repo, install all dependencies, and start the development server: git clone git@github.com:oceanprotocol/docs.git cd docs/ +# add GITHUB_TOKEN +cp .env.sample .env +vi .env + npm i npm start ``` +For getting your `GITHUB_TOKEN`, see [GitHub GraphQL API](#github-graphql-api) + This will start a hot-reloading local server exposed under [localhost:8000](http://localhost:8000). ### Use Docker @@ -125,6 +139,7 @@ Alternatively, you can use Docker for which you need to have installed on your m - [Docker](https://www.docker.com) - [Docker Compose](https://docs.docker.com/compose/) +- `GITHUB_TOKEN` in `.env`, see [GitHub GraphQL API](#github-graphql-api) Then use Compose to bring everything up: @@ -145,7 +160,7 @@ For local development, you can simply [create a personal access token](https://g ```bash cp .env.sample .env vi .env -# GITHUB_TOKEN=ADD-YOUR-TOKEN-HERE +# GITHUB_TOKEN=add_your_token_here ``` When running the site locally, you can use the GraphiQL client running under [localhost:8000/\_\_\_graphql](http://localhost:8000/___graphql) to explore the whole GraphQL layer of the site (not just the GitHub infos). @@ -164,10 +179,6 @@ query { name description url - forkCount - stargazers { - totalCount - } } } } diff --git a/content/concepts/contributing.md b/content/concepts/contributing.md index f3cfec2b..38c7576a 100644 --- a/content/concepts/contributing.md +++ b/content/concepts/contributing.md @@ -17,6 +17,8 @@ To write an issue, go to the relevant GitHub repository, click on the Issues tab To make a feature request or proposal, you can go to the [🐙 Ocean Protocol Enhancement Proposals (OEPs)](https://github.com/oceanprotocol/OEPs/) repository and write a proposal. + + ## Write Docs If you’re writing code, you should also update any related docs. However, you might want to write docs only, such as: @@ -26,3 +28,16 @@ If you’re writing code, you should also update any related docs. However, you - Courses - Code explanations - News from recent events + +For instructions on how to contribute to our main documentation check out the docs repo. + + + +## Fix an Issue + +... Where to look for issues? +... With 'help wanted' label? + +## Participate in a bounty + +- [Bounties](/concepts/bounties/) diff --git a/content/concepts/development.md b/content/concepts/development.md index 2ddbf96c..81cb38a6 100644 --- a/content/concepts/development.md +++ b/content/concepts/development.md @@ -17,4 +17,6 @@ We use GitHub as a means for maintaining and tracking issues, roadmap and source - [Business Board (Ocean Roadmap)](https://github.com/oceanprotocol/ocean/projects/1) - [Milestones](https://github.com/oceanprotocol/ocean/milestones?direction=asc&sort=due_date&state=open) +We use the _dev-ocean_ repository for internal documentation of most of our engineering processes. + diff --git a/content/test.md b/content/test.md index 67cabdf5..3f8c37b4 100644 --- a/content/test.md +++ b/content/test.md @@ -385,7 +385,7 @@ Note that the component name in Markdown needs to be always in lowercase, and ha ### Repository -The `Repository` component fetching and displaying information about a GitHub repo. can be used as `` Component requires a `name` to be passed: +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: ```