Skip to content

Commit 6000566

Browse files
jenweberjenweber
committed
Documentation and cleanup
1 parent 3ab9e91 commit 6000566

File tree

7 files changed

+70
-147
lines changed

7 files changed

+70
-147
lines changed

‎MAINTAINERS.md

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
# Maintainers
2+
3+
In order to release a new version of the API docs manually, follow these steps.
4+
5+
1. Make sure you have the latest version of this repository, `ember.js`,
6+
`ember-data`, `ember-api-docs-data`, and `ember-api-docs`.
7+
2. Make sure you have a clean working directory in each repository,
8+
i.e. `git status`
9+
3. Go through the steps in the README to generate the docs and preview
10+
them in the web app
11+
4. If everything looks good, commit the changes to `ember-api-docs-data`
12+
and open a pull request to that repository.
13+
14+
When the pull request is merged in `ember-api-docs-data`, the files
15+
will be synced automatically to S3.
16+
Either you can wait for them to show up in the deployed website,
17+
or you can clear the Fastly cache to force them to show up faster.

‎README.md

Lines changed: 44 additions & 127 deletions
Original file line numberDiff line numberDiff line change
@@ -1,159 +1,76 @@
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-
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:
3+
This tool gets the code comments from `ember.js` and `ember-data` libraries,
4+
turns them into JSON files, and then turns those JSON files into a
5+
[JSON:API](http://jsonapi.org/) format.
46

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.
7+
The files this tool creates are used to power
8+
[api.emberjs.com](https://api.emberjs.com).
89

9-
All the generated files are stored in the `tmp` folder under the project root:
1010

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-
```
17-
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.
11+
> ℹ️ **NOTE:** If you are looking for the front end app behind https://api.emberjs.com/, visit [ember-api-docs](https://github.com/ember-learn/ember-api-docs) instead.
1912
2013
## Prerequisites
2114

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.
25-
26-
## Quickstart
27-
28-
### Generate Docs from Ember Source
15+
- the latest [Node.js](https://nodejs.org/) LTS
16+
- [yarn v1](https://yarnpkg.com/)
2917

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/).
18+
Clone all of the following repositories into the same directory,
19+
and `yarn install` in each one:
3120

32-
```bash
33-
# Clone Ember.js and Ember Data repositories into the same root folder.
34-
git clone https://github.com/emberjs/ember.js/
35-
git clone https://github.com/emberjs/data
21+
- This repository, `ember-jsonapi-docs`
22+
- [ember-api-docs-data](https://github.com/ember-learn/ember-api-docs-data)
23+
- [ember.js](https://github.com/emberjs/ember.js)
24+
- [ember-data](https://github.com/emberjs/data/)
3625

37-
# Clone this repository into the same root folder.
38-
git clone https://github.com/ember-learn/ember-jsonapi-docs
39-
cd ember-jsonapi-docs
26+
## Generate docs
4027

41-
# Install the dependencies.
42-
yarn
28+
Decide which version and project you want to build docs for.
29+
Then, in `ember.js` and/or `ember-data` repositories, check out the version
30+
tags you want to generate docs for. For example:
4331

44-
# Generate docs for a particular project from its local repository.
45-
# Version should match the one in `package.json` of a target project.
46-
yarn gen --project ember --version 3.17.0
47-
yarn gen --project ember-data --version 3.17.0
48-
49-
# Run API locally.
50-
yarn serve
32+
```sh
33+
git checkout v3.20.0
5134
```
5235

53-
> ℹ️ **NOTE:** `--version` should match the one in the `package.json` of a target Ember project. If `package.json` uses a release name (e.g. `beta` or `canary`), omit it and use only numbers. For example, if the `package.json` says `3.19.0-beta.2`, use `3.19.0`.
54-
55-
> ✅ **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.
36+
Generate the JSON docs for `ember` and/or `ember-data`. This will add new JSON
37+
files into the `s3-docs` directory of `ember-api-docs-data`:
5638

57-
### Generate Docs from YUIDoc Files Stored in AWS
58-
59-
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/).
60-
61-
> ⚠️ **WARNING:** The app tries to process all Ember.js and Ember Data versions since 1.0 which takes high memory & time to complete.
62-
63-
```bash
64-
# Clone the repository.
65-
git clone https://github.com/ember-learn/ember-jsonapi-docs
66-
cd ember-jsonapi-docs
67-
68-
# Install the dependencies.
69-
yarn
70-
71-
# Set environment variables to get access to s3://api-docs.emberjs.com.
72-
# Use Access Keys generated in step 3 in "Prerequisites".
73-
export AWS_ACCESS_KEY_ID=xxxxxx
74-
export AWS_SECRET_ACCESS_KEY=xxxxx
75-
76-
# Download YUIDoc docs and index files for all projects/releases from s3://api-docs.emberjs.com.
77-
# Then, generate JSON:API-comlaint docs from the downloaded files.
78-
yarn start --sync --max_old_space_size=8192
79-
80-
# At this point, you can also generate JSON:API-comlaint docs only for
81-
# a particular project/release.
82-
yarn start --project ember --version 3.17.0
83-
yarn start --project ember-data --version 3.17.0
84-
85-
# Run API locally.
86-
yarn serve
39+
```sh
40+
yarn gen --project ember --version "3.20.0"
41+
yarn gen --project ember-data --version "3.20.0"
8742
```
8843

89-
> ℹ️ **NOTE:** If docs for a particular version are missing in `s3://api-docs.emberjs.com`, the tool downloads them from npm (e.g. https://unpkg.com/[email protected]/docs/data.json) as a fallback.
44+
Now, run this command to parse the `s3-docs` files into JSON:API docs for
45+
`ember` and/or `ember-data`.
46+
This will add new files into `json-docs` and `rev-index` in `ember-api-docs-data`.
9047

91-
## Overriding a specific version of YUIDoc file with a local copy (for core contributors).
92-
93-
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.
94-
95-
> ⚠️ **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.
96-
97-
```bash
98-
# Set environment variables.
99-
export AWS_ACCESS_KEY_ID=xxxxxx
100-
export AWS_SECRET_ACCESS_KEY=xxxxx
101-
102-
# Download YUIDoc docs and index files for all releases from s3://api-docs.emberjs.com.
103-
# This is important so that we don't loose other versions of docs that
104-
# are already out there when the index files are generated.
105-
yarn start --sync --max_old_space_size=8192
106-
107-
# Go to the folder and and replace a YUIDoc file that you want to be processed.
108-
# Ensure that the file name is same as the one that's already there.
109-
cd tmp/s3-docs/<VERSION_TO_REPLACE>
48+
```
49+
yarn start --project ember --version "3.20.0"
50+
yarn start --project ember-data --version "3.20.0"
51+
```
11052

111-
# Set an environment variable to enable publishing to s3://api-docs.emberjs.com.
112-
export AWS_SHOULD_PUBLISH=yes
53+
> ℹ️ **NOTE:** `--version` should match the one in the `package.json` of a target Ember project. If `package.json` uses a release name (e.g. `beta` or `canary`), omit it and use only numbers. For example, if the `package.json` says `3.19.0-beta.2`, use `3.19.0`.
11354
114-
# Regenerate JSON:API-comlaint docs only for a particular project/release and
115-
# publish them to s3://api-docs.emberjs.com...
116-
yarn start --project ember --version <VERSION_TO_REPLACE> --ignorePreviouslyIndexedDoc
117-
yarn start --project ember-data --version <VERSION_TO_REPLACE> --ignorePreviouslyIndexedDoc
55+
> ✅ **TIP:** If you are debugging failed builds, periodically discard the changes
56+
made to `ember-api-docs-data`, since changes are made in-place.
11857

119-
# OR
120-
# Regenerate JSON:API-comlaint docs for ALL projects/releases regardless of indexed version and
121-
# publish them to s3://api-docs.emberjs.com.
122-
yarn start --clean --max_old_space_size=8192
123-
```
58+
## View the generated docs in a web app
12459

125-
## Running from GitHub
60+
From the [ember-api-docs-data](https://github.com/ember-learn/ember-api-docs-data)
61+
repository, start a server for the JSON files:
12662

12763
```
128-
git clone [email protected]:ember-learn/ember-api-docs-data.git
129-
git clone [email protected]:emberjs/ember.js.git && cd ember.js && yarn install
130-
git clone [email protected]:ember-learn/ember-jsonapi-docs.git && cd ember-jsonapi-docs.git && yarn install
131-
yarn gen --project ember --version "3.24.0"
132-
yarn start --project ember --version "3.24.0"
64+
yarn serve
13365
```
13466

135-
## Backing Up Docs
136-
137-
If you plan to run a major migration, back up all the content to a timestamped folder in the Amazon S3 bucket.
67+
Clone the [ember-api-docs](https://github.com/ember-learn/ember-api-docs)
68+
repository, install dependencies, and start the front end in "local" mode:
13869

139-
```bash
140-
yarn backup
14170
```
142-
143-
## FAQ
144-
145-
### Can I use API from the [ember-api-docs](https://github.com/ember-learn/ember-api-docs) app?
146-
147-
Yes, follow one of the quickstarts and then run the `ember-api-docs` application using the following commands.
148-
149-
```bash
150-
# Clone the repository with the "ember-api-docs" app.
15171
git clone https://github.com/ember-learn/ember-api-docs
152-
cd ember-api-docs
153-
154-
# Install the dependencies.
155-
yarn
156-
157-
# Run the application side by side with a locally running API.
72+
yarn install
15873
yarn start:local
15974
```
75+
76+
Visit the app in your browser at [http://localhost:4200](http://localhost:4200)

‎generate-local.js

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -55,6 +55,10 @@ const runCmd = async (cmd, path) => {
5555
}
5656
}
5757

58+
// If someone enters the project version as `v3.20.0` instead of `3.20.0`,
59+
// handle it gracefully.
60+
version = version.replace('v', '');
61+
5862
let buildDocs = async projDirPath => {
5963
checkIfProjectDirExists(projDirPath)
6064
await runCmd('yarn', projDirPath)
@@ -69,8 +73,6 @@ const runCmd = async (cmd, path) => {
6973
removeSync(projYuiDocFile)
7074
removeSync(`${docsPath}/json-docs/${project}/${version}`)
7175

72-
mkdirpSync(`tmp/s3-docs/v${version}`)
73-
7476
const yuiDocFile = path.join(
7577
projDirPath,
7678
project === 'ember' ? 'docs/data.json' : 'packages/-ember-data/dist/docs/data.json'
@@ -91,7 +93,6 @@ const runCmd = async (cmd, path) => {
9193
project,
9294
'--version',
9395
version,
94-
'--ignorePreviouslyIndexedDoc',
9596
'--no-sync'
9697
]).stdout.pipe(process.stdout)
9798
})()

‎index.js

Lines changed: 1 addition & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -9,10 +9,8 @@ let projects =
99
argv.project && possibleProjects.includes(argv.project) ? [argv.project] : possibleProjects
1010
let specificDocsVersion = argv.version ? argv.version : ''
1111

12-
let ignorePreviouslyIndexedDoc =
13-
projects.length !== 0 && specificDocsVersion !== '' && argv.ignorePreviouslyIndexedDoc
1412
let runClean = !!argv.clean
1513
let noSync = !argv.sync
1614

1715
const { apiDocsProcessor } = require('./main.js')
18-
apiDocsProcessor(projects, specificDocsVersion, ignorePreviouslyIndexedDoc, runClean, noSync)
16+
apiDocsProcessor(projects, specificDocsVersion, runClean, noSync)

‎lib/read-docs.js

Lines changed: 1 addition & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,6 @@ const docsPath = '../ember-api-docs-data';
99
export default function readDocs(
1010
projects,
1111
specificVersion = '',
12-
ignorePreviouslyIndexedDoc = false,
1312
runClean = false
1413
) {
1514
return projects.reduce(async (prevPromise, projectName) => {
@@ -35,14 +34,9 @@ export default function readDocs(
3534
)
3635

3736
if (!runClean) {
38-
if (!ignorePreviouslyIndexedDoc) {
39-
availableSourceVersions = availableSourceVersions.filter(
40-
version => !prevIndexedVersions.includes(version)
41-
)
42-
}
4337

4438
folders = folders.filter(f => {
45-
if (!prevIndexedVersions.includes(f) || ignorePreviouslyIndexedDoc) {
39+
if (!prevIndexedVersions.includes(f)) {
4640
return f
4741
} else {
4842
let version = f.replace(`${docsPath}/s3-docs/v`, '').replace(`/${projectName}-docs.json`, '')

‎main.js

Lines changed: 2 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -17,7 +17,6 @@ const docsPath = '../ember-api-docs-data';
1717
export async function apiDocsProcessor(
1818
projects,
1919
specificDocsVersion,
20-
ignorePreviouslyIndexedDoc,
2120
runClean,
2221
) {
2322
RSVP.on('error', reason => {
@@ -31,8 +30,8 @@ export async function apiDocsProcessor(
3130

3231
await RSVP.Promise.all(filesToProcess.map(fixBorkedYuidocFiles))
3332

34-
console.log(projects, specificDocsVersion, ignorePreviouslyIndexedDoc, runClean)
35-
await readDocs(projects, specificDocsVersion, ignorePreviouslyIndexedDoc, runClean)
33+
console.log(projects, specificDocsVersion, runClean)
34+
await readDocs(projects, specificDocsVersion, runClean)
3635
.then(docs => {
3736
return RSVP.map(projects, projectName => {
3837
return RSVP.map(docs[projectName], doc => {

‎package.json

Lines changed: 1 addition & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -63,8 +63,5 @@
6363
"mocha": "^6.2.0",
6464
"prettier": "1.18.2",
6565
"pretty-quick": "^1.11.1"
66-
},
67-
"cacheDirectories": [
68-
"tmp"
69-
]
66+
}
7067
}

0 commit comments

Comments
 (0)