oceanprotocol/docs
1
0
Fork 0
mirror of https://github.com/oceanprotocol/docs.git synced 2024-11-26 19:49:26 +01:00
Code Releases Activity

Moved submodule tips under Development

Browse Source 
and tweaked some git commands
This commit is contained in:
Troy McConaghy 2018-11-20 13:53:11 +01:00
parent 3ab265da04
commit c11bdf6bb8
1 changed files with 45 additions and 39 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

84
README.md
View File

@ -18,7 +18,6 @@
--- ---
- [Living with Submodules](#living-with-submodules)
- [Content](#content) - [Content](#content)
- [Content Files](#content-files) - [Content Files](#content-files)
- [External Content Files](#external-content-files) - [External Content Files](#external-content-files)
@ -27,41 +26,15 @@
- [Editing Docs](#editing-docs) - [Editing Docs](#editing-docs)
- [Repositories](#repositories) - [Repositories](#repositories)
- [Development](#development) - [Development](#development)
- [Use Docker](#use-docker) - [Using npm](#using-npm)
- [Linting & formatting](#linting--formatting) - [Using Docker](#use-docker)
- [Editor setup: VS Code](#editor-setup-vs-code) - [Linting & Formatting](#linting--formatting)
- [Editor Setup: VS Code](#editor-setup-vs-code)
- [GitHub GraphQL API](#github-graphql-api) - [GitHub GraphQL API](#github-graphql-api)
- [Deployment](#deployment) - [Deployment](#deployment)
- [Authors](#authors) - [Authors](#authors)
- [License](#license) - [License](#license)
## Living with Submodules
This Git repo has [Git submodules](https://git-scm.com/book/en/v2/Git-Tools-Submodules). They are the subdirectories of `external/`. Each one is basically another Git repo, i.e. an external Git repo that just _looks_ like it's part of this Git repo. It's very easy to get Git into a confusing state when there are submodules. If you follow the following tips, you should probably be okay:
1. Clone this repo using:
```bash
git clone --recurse-submodules git@github.com:oceanprotocol/docs.git
```
1. Don't edit anything in the submodules (i.e. in `external/`). Instead, edit it over in the other Git repository and merge your changes over there.
1. Get all the submodules up-to-date using:
```bash
git submodule update --remote
```
That will get each submodule up-to-date with the HEAD commit of some branch in a remote repository. Which branch? That's set in the `.gitmodules` file. You can check the current commit hashes of all the submodules using `git submodule status`
1. Before doing any `git checkout ...` or other normal Git operations, do this:
```bash
git config --global submodule.recurse true
```
That's like adding the `--recurse-submodules` option to all those Git commands (except for `git clone`) so you don't have to.
## Content ## Content
The documentation is split in multiple sections whose content lives in this repo: The documentation is split in multiple sections whose content lives in this repo:
@ -199,15 +172,43 @@ in [`/data/repositories.yml`](data/repositories.yml).
The site is a React app built with [Gatsby](https://www.gatsbyjs.org). The site is a React app built with [Gatsby](https://www.gatsbyjs.org).
As a prerequisite you'll need on your machine: This Git repo has [Git submodules](https://git-scm.com/book/en/v2/Git-Tools-Submodules). They are the subdirectories of `external/`. Each one is basically another Git repo, i.e. an external Git repo that just _looks_ like it's part of this Git repo. It's very easy to get Git into a confusing state when there are submodules. If you follow the following tips, you should probably be okay:
1. Clone this repo using:
```bash
git clone --recurse-submodules git@github.com:oceanprotocol/docs.git
```
1. Don't edit anything in the submodules (i.e. in `external/`). Instead, edit it over in the other Git repository and merge your changes over there.
1. Get all the submodules up-to-date using:
```bash
git submodule update --remote --recursive
```
That will get each submodule up-to-date with the HEAD commit of some branch in a remote repository. Which branch? That's set in the `.gitmodules` file. You can check the current commit hashes of all the submodules using `git submodule status`
1. Before doing any `git checkout ...` or other normal Git operations, do this:
```bash
git config --global submodule.recurse true
```
That's like adding the `--recurse-submodules` option to all those Git commands (except for `git clone`) so you don't have to.
### Using npm
As a prerequisite, you'll need the following on your machine:
- Node.js - Node.js
- npm - npm
- Your `GITHUB_TOKEN`, see [GitHub GraphQL API](#github-graphql-api)
Clone this repo, install all dependencies, and start the development server: Clone this repo, install all dependencies, and start the development server:
```bash ```bash
git clone --recursive git@github.com:oceanprotocol/docs.git git clone --recurse-submodules git@github.com:oceanprotocol/docs.git
cd docs/ cd docs/
# add GITHUB_TOKEN # add GITHUB_TOKEN
@ -218,27 +219,32 @@ npm i
npm start 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). This will start a hot-reloading local server exposed under [localhost:8000](http://localhost:8000).
### Use Docker ### Using Docker
Alternatively, you can use Docker for which you need to have installed on your machine: Alternatively, you can use Docker for which you need to have installed on your machine:
- [Docker](https://www.docker.com) - [Docker](https://www.docker.com)
- [Docker Compose](https://docs.docker.com/compose/) - [Docker Compose](https://docs.docker.com/compose/)
- `GITHUB_TOKEN` in `.env`, see [GitHub GraphQL API](#github-graphql-api) - Your `GITHUB_TOKEN`, see [GitHub GraphQL API](#github-graphql-api)
Then use Docker Compose to bring everything up: Then use Docker Compose to bring everything up:
```bash ```bash
git clone --recurse-submodules git@github.com:oceanprotocol/docs.git
cd docs/
# add GITHUB_TOKEN
cp .env.sample .env
vi .env
docker-compose up docker-compose up
``` ```
This will expose a hot-reloading server under [localhost:8000](http://localhost:8000). This will expose a hot-reloading server under [localhost:8000](http://localhost:8000).
## Linting & formatting ## Linting & Formatting
To enforce a consistent code style, linting is setup for pretty much every file. Linting is part of the test suite, meaning builds on Travis will fail in case of linting errors. To enforce a consistent code style, linting is setup for pretty much every file. Linting is part of the test suite, meaning builds on Travis will fail in case of linting errors.
@ -257,7 +263,7 @@ npm run lint
npm run format npm run format
``` ```
### Editor setup: VS Code ### Editor Setup: VS Code
If you use VS Code as your editor, you can install those extensions to get linting as you type, and auto-formatting as you save: If you use VS Code as your editor, you can install those extensions to get linting as you type, and auto-formatting as you save: