Skip to content

Commit fc205d1

Browse files
sivakumar-kailasamsivakumar-kailasam
authored
Merge pull request #85 from alexeykostevich/doc/readme-update
 Update README with more details about the project and its setup.
2 parents 4c35c37 + 819738e commit fc205d1

File tree

1 file changed

+125
-47
lines changed

1 file changed

+125
-47
lines changed

‎README.md

Lines changed: 125 additions & 47 deletions
Original file line numberDiff line numberDiff line change
@@ -1,66 +1,144 @@
11
# Ember JSON API Docs [![Build Status](https://travis-ci.org/ember-learn/ember-jsonapi-docs.svg?branch=master)](https://travis-ci.org/ember-learn/ember-jsonapi-docs)
22

3-
If you are looking for the app behind https://emberjs.com/api/, visit
4-
[ember-api-docs](https://github.com/ember-learn/ember-api-docs) instead. This ember-jsonapi-docs
5-
repository is internal tooling that is not required to run the ember-api-docs app locally.
3+
This is an internal tool for generating API docs for the Ember.js framework and exposing it through [JSON:API](http://jsonapi.org/) for various applications (e.g. https://api.emberjs.com/). The tool allows you to:
64

7-
`ember-jsonapi-docs` is for turning code comments in [ember.js](https://github.com/emberjs/ember.js) into
8-
[json api](http://jsonapi.org/) compliant data for use in various applications seeking to use the Ember API.
5+
- Generate API docs from [YUIDoc](http://yui.github.io/yuidoc/syntax/index.html) comments in the [emberjs/ember.js](https://github.com/emberjs/ember.js/) and [emberjs/data](https://github.com/emberjs/data) repositories in [YUIDoc](http://yui.github.io/yuidoc/) and [JSON:API](http://jsonapi.org/) formats.
6+
- Publish docs to an Amazon S3 bucket (`s3://api-docs.emberjs.com`).
7+
- Expose API docs in the JSON:API format through API.
98

10-
The script pulls yuidoc build output from all Ember versions from Amazon S3, converts it to json api format and creates an archive. It can also be run to build jsonapi docs from a local copy of ember.js.
9+
All the generated files are stored in the `tmp` folder under the project root:
1110

12-
## Running the app
11+
```
12+
tmp
13+
├── json-docs // JSON:API-comlaint docs generated locally from YUIDoc files in `s3-docs`.
14+
├── rev-index // Rev index files used for generating JSON:API-comlaint docs.
15+
├── s3-docs // YUIDoc docs generated locally or downloaded from s3://api-docs.emberjs.com.
16+
```
1317

14-
1. Fork/Clone [ember-jsonapi-docs](https://github.com/ember-learn/ember-jsonapi-docs)
15-
1. Run `yarn`
16-
1. Install the [aws cli](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-install.html)
17-
1. Set up AWS access
18+
> ℹ️ **NOTE:** If you are looking for the app behind https://api.emberjs.com/, visit [ember-api-docs](https://github.com/ember-learn/ember-api-docs) instead.
1819
19-
```shell
20-
export AWS_ACCESS_KEY_ID=xxxxxx
21-
export AWS_SECRET_ACCESS_KEY=xxxxx
22-
```
20+
## Prerequisites
2321

24-
The app accesses builds.emberjs.com (an Amazon S3 bucket) in read-only mode, which is public. This requires any valid AWS credentials.
22+
1. Install the latest [Node.js](https://nodejs.org/) LTS.
23+
2. Install [AWS CLI version 2](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-install.html).
24+
3. Create an account in [AWS Management Console](https://console.aws.amazon.com). [Create a New Access Key](https://docs.aws.amazon.com/general/latest/gr/managing-aws-access-keys.html) (access key ID and secret access key) in *My Security Credentials* under your profile name to be able to access public AWS S3 buckets.
2525

26-
You can get your credentials by logging into your [AWS console](https://console.aws.amazon.com) and navigating to "_My Security Credentials_" under your profile name. You can generate a new pair under the "_Access Keys (Access Key ID and Secret Access Key)_" section.
26+
## Quickstart
2727

28-
1. To test your changes in the app run,
29-
`yarn start`
30-
The app tries to process all ember & ember-data versions since 1.0 which takes high memory & time to complete. If you intend it, then run `yarn start --max_old_space_size=8192`.
31-
You are setting your node max heap space to 8GB, so make sure you have that much space available on your machine.
28+
### Generate Docs from Ember Source
3229

33-
## To Generate docs for a specific project and/or version for development
30+
You can generate docs from your local copies of [emberjs/ember.js](https://github.com/emberjs/ember.js/) and [emberjs/data](https://github.com/emberjs/data) repositories and serve them locally as [JSON:API](http://jsonapi.org/).
3431

35-
You can do this by passing `--project ember/ember-data --version 2.11.1` as an argument to the index script. e.g., `yarn start --project ember --version 2.11.0`.
36-
You need an additional flag `AWS_SHOULD_PUBLISH=true` for publishing the docs.
32+
```bash
33+
# Clone Ember.js and Ember Data repositories.
34+
git clone https://github.com/emberjs/ember.js/
35+
git clone https://github.com/emberjs/data
3736

38-
## To override a specific version of a doc with a different yuidoc from your machine (For core contributors)
37+
# Clone the repository into the same root folder.
38+
git clone https://github.com/ember-learn/ember-jsonapi-docs
39+
cd ember-jsonapi-docs
3940

40-
- Read this section first!
41-
- We assume you have the keys to the kingdom before you start doing this (AWS keys to publish to api-docs.emberjs.com & all necessary env variables that need to be set) 😄
42-
- In its present form this should be used only when there aren't new docs out there that are yet to be processed. As in if ember 3.3 is released but isn't indexed yet you should wait for this app to finish processing it via the cron job we have on heroku before you can proceed to modify any of the existing docs from your machine.
43-
- First run `yarn start` so that you have all the docs from s3 on your local. This is important so that we don't loose other versions of docs that are already out there when the index files are generated
44-
- Then go to `./tmp/s3-docs/<the_version_you_want_to_replace>` and override the file there with the yuidoc file that you want to be processed. Ensure that the file name is same as the one that's already there.
45-
- Then run `yarn start --project=ember-data --version=3.2.0 --ignorePreviouslyIndexedDoc`. Make sure you enter the entire version(including patch version).
46-
- To run against all versions of ember and ember-data regardless of indexed version, run `node --max_old_space_size=8192 index.js --clean`
41+
# Install the dependencies.
42+
yarn
4743

48-
## Generating API Documentation and Testing API Docs Locally
44+
# Generate docs for a particular project/release.
45+
yarn gen --project ember --version 3.17.0
46+
yarn gen --project ember-data --version 3.17.0
4947

50-
These steps are only necessary if you are trying to run the ember-api-docs
51-
app with documentation pulled from a local copy of ember.js.
48+
# Run API locally.
49+
yarn serve
50+
```
5251

53-
1. Clone the following 4 repositories into a single parent directory. Install dependencies for each app as described in their respective `README` files.
54-
- [ember.js](https://github.com/emberjs/ember.js)
55-
- [data (ember data)](https://github.com/emberjs/data)
56-
- [ember-jsonapi-docs](https://github.com/ember-learn/ember-jsonapi-docs)
57-
- [ember-api-docs](https://github.com/ember-learn/ember-api-docs)
58-
1. Set up the project according to the instructions above in `Running the app`.
59-
1. From the `ember-jsonapi-docs` directory, run `yarn gen --project ember --version 2.18.0`. This command runs the Ember documentation build, generates jsonapi output, copies it to the `ember-api-docs` directory & runs this app. To build ember data documentation, run `yarn gen --project ember-data --version 2.18.0`.
60-
- If you are debugging failed builds, periodically clear out the contents of the `tmp` directory, and run the script again. Past failed runs can cause subsequent runs to fail in unexpected ways.
61-
1. Run `yarn server` in this app to serve the content locally.
62-
1. Run the API app with the newly generated local data by running `yarn server` in this app & then run `yarn start:local` in the `ember-api-docs` directory.
52+
> ✅ **TIP:** If you are debugging failed builds, periodically clear out the contents of the `tmp` directory, and run the script again. Past failed runs can cause subsequent runs to fail in unexpected ways.
6353
64-
## Backing up docs before running major migrations
54+
### Generate Docs from YUIDoc Files Stored in AWS
6555

66-
If you plan to run a major migration run `yarn backup` so that all the content are safely backed up to a timestamped s3 folder.
56+
All [Ember.js](https://github.com/emberjs/ember.js/) and [Ember.js Data](https://github.com/emberjs/data) releases have already generated docs in a public Amazon S3 bucket (`s3://api-docs.emberjs.com`). You can download them and serve locally as [JSON:API](http://jsonapi.org/).
57+
58+
> ⚠️ **WARNING:** The app tries to process all Ember.js and Ember Data versions since 1.0 which takes high memory & time to complete.
59+
60+
```bash
61+
# Clone the repository.
62+
git clone https://github.com/ember-learn/ember-jsonapi-docs
63+
cd ember-jsonapi-docs
64+
65+
# Install the dependencies.
66+
yarn
67+
68+
# Set environment variables to get access to s3://api-docs.emberjs.com.
69+
# Use Access Keys generated in step 3 in "Prerequisites".
70+
export AWS_ACCESS_KEY_ID=xxxxxx
71+
export AWS_SECRET_ACCESS_KEY=xxxxx
72+
73+
# Download YUIDoc docs and index files for all projects/releases from s3://api-docs.emberjs.com.
74+
# Then, generate JSON:API-comlaint docs from the downloaded files.
75+
yarn start --sync --max_old_space_size=8192
76+
77+
# At this point, you can also generate JSON:API-comlaint docs only for
78+
# a particular project/release.
79+
yarn start --project ember --version 3.17.0
80+
yarn start --project ember-data --version 3.17.0
81+
82+
# Run API locally.
83+
yarn serve
84+
```
85+
86+
## Overriding a specific version of YUIDoc file with a local copy (for core contributors).
87+
88+
To proceed, you need AWS Access Keys to publish to [api-docs.emberjs.com](http://api-docs.emberjs.com/) and all necessary environemnt variables set.
89+
90+
> ⚠️ **WARNING:** In its present form this should be used only when there aren't new docs out there that are yet to be processed. For example, if Ember 3.17 is released but isn't indexed yet you should wait for this app to finish processing it via the cron job on Heroku before you can proceed to modify any of the existing docs from your machine.
91+
92+
```bash
93+
# Set environment variables.
94+
export AWS_ACCESS_KEY_ID=xxxxxx
95+
export AWS_SECRET_ACCESS_KEY=xxxxx
96+
97+
# Download YUIDoc docs and index files for all releases from s3://api-docs.emberjs.com.
98+
# This is important so that we don't loose other versions of docs that
99+
# are already out there when the index files are generated.
100+
yarn start --sync --max_old_space_size=8192
101+
102+
# Go to the folder and and replace a YUIDoc file that you want to be processed.
103+
# Ensure that the file name is same as the one that's already there.
104+
cd tmp/s3-docs/<VERSION_TO_REPLACE>
105+
106+
# Set an environment variable to enable publishing to s3://api-docs.emberjs.com.
107+
export AWS_SHOULD_PUBLISH=yes
108+
109+
# Regenerate JSON:API-comlaint docs only for a particular project/release and
110+
# publish them to s3://api-docs.emberjs.com...
111+
yarn start --project ember --version <VERSION_TO_REPLACE> --ignorePreviouslyIndexedDoc
112+
yarn start --project ember-data --version <VERSION_TO_REPLACE> --ignorePreviouslyIndexedDoc
113+
114+
# OR
115+
# Regenerate JSON:API-comlaint docs for ALL projects/releases regardless of indexed version and
116+
# publish them to s3://api-docs.emberjs.com.
117+
yarn start --clean --max_old_space_size=8192
118+
```
119+
120+
## Backing Up Docs
121+
122+
If you plan to run a major migration, back up all the content to a timestamped folder in the Amazon S3 bucket.
123+
124+
```bash
125+
yarn backup
126+
```
127+
128+
## FAQ
129+
130+
### Can I use API from the [ember-api-docs](https://github.com/ember-learn/ember-api-docs) app?
131+
132+
Yes, follow one of the quickstarts and then run the `ember-api-docs` application using the following commands.
133+
134+
```bash
135+
# Clone the repository with the "ember-api-docs" app.
136+
git clone https://github.com/ember-learn/ember-api-docs
137+
cd ember-api-docs
138+
139+
# Install the dependencies.
140+
yarn
141+
142+
# Run the application side by side with a locally running API.
143+
yarn start:local
144+
```

0 commit comments

Comments
 (0)