Skip to content

Commit

Permalink
Generate doc info for RN components
Browse files Browse the repository at this point in the history 
Summary:
We used to generate the documentation for the website but moved the docs to another repo.

There is some work on the docs to be able to ingest info from this repo in order to go back to generating API information. The current thinking is we will generate this JSON file and the website repo will pull it in to generate the docs.

I plan to make the script run on CI and fail if the generated file isn't updated, in a follow up PR.

Reviewed By: zackargyle

Differential Revision: D17183936

fbshipit-source-id: 99ce3fa5d7becc0ef20df5d439b175eedbe546f3
  • Loading branch information
@TheSavior @facebook-github-bot
TheSavior authored and facebook-github-bot committed Sep 20, 2019
1 parent 0baacbe commit eb7dbc8
Show file tree
Hide file tree
Showing 5 changed files with 292 additions and 0 deletions.
1 change: 1 addition & 0 deletions Libraries/Components/Switch/Switch.js
View file
Expand Up @@ -6,6 +6,7 @@
*
* @flow
* @format
* @generate-docs
*/

'use strict';
Expand Down
195 changes: 195 additions & 0 deletions docs/generatedComponentApiDocs.js
View file
@@ -0,0 +1,195 @@
/**
* Copyright (c) Facebook, Inc. and its affiliates.
*
* This source code is licensed under the MIT license found in the
* LICENSE file in the root directory of this source tree.
*
* This file is used by the React Native website to show the props of core components
* This file was generated by running scripts/generate-api-docs.js
*
* @generated SignedSource<<99203c7cf79ad84e3ce1e508a22416fe>>
*/

'use strict';

module.exports = [
{
"description": "A visual toggle between two mutually exclusive states.\n\nThis is a controlled component that requires an `onValueChange` callback that\nupdates the `value` prop in order for the component to reflect user actions.\nIf the `value` prop is not updated, the component will continue to render the\nsupplied `value` prop instead of the expected result of any user actions.",
"displayName": "Switch",
"methods": [],
"props": {
"disabled": {
"required": false,
"flowType": {
"name": "boolean",
"nullable": true
},
"description": "Whether the switch is disabled. Defaults to false."
},
"value": {
"required": false,
"flowType": {
"name": "boolean",
"nullable": true
},
"description": "Boolean value of the switch. Defaults to false."
},
"thumbColor": {
"required": false,
"flowType": {
"name": "ColorValue",
"nullable": true
},
"description": "Custom color for the switch thumb."
},
"trackColor": {
"required": false,
"flowType": {
"name": "$ReadOnly",
"elements": [
{
"name": "signature",
"type": "object",
"raw": "{|\n false?: ?ColorValue,\n true?: ?ColorValue,\n|}",
"signature": {
"properties": [
{
"key": "false",
"value": {
"name": "ColorValue",
"nullable": true,
"required": false
}
},
{
"key": "true",
"value": {
"name": "ColorValue",
"nullable": true,
"required": false
}
}
]
}
}
],
"raw": "$ReadOnly<{|\n false?: ?ColorValue,\n true?: ?ColorValue,\n|}>",
"nullable": true
},
"description": "Custom colors for the switch track.\n\nNOTE: On iOS when the switch value is false, the track shrinks into the\nborder. If you want to change the color of the background exposed by the\nshrunken track, use `ios_backgroundColor`."
},
"ios_backgroundColor": {
"required": false,
"flowType": {
"name": "ColorValue",
"nullable": true
},
"description": "On iOS, custom color for the background. This background color can be seen\neither when the switch value is false or when the switch is disabled (and\nthe switch is translucent)."
},
"onChange": {
"required": false,
"flowType": {
"name": "signature",
"type": "function",
"raw": "(event: SwitchChangeEvent) => Promise<void> | void",
"signature": {
"arguments": [
{
"name": "event",
"type": {
"name": "SyntheticEvent",
"elements": [
{
"name": "$ReadOnly",
"elements": [
{
"name": "signature",
"type": "object",
"raw": "{|\n value: boolean,\n|}",
"signature": {
"properties": [
{
"key": "value",
"value": {
"name": "boolean",
"required": true
}
}
]
}
}
],
"raw": "$ReadOnly<{|\n value: boolean,\n|}>"
}
],
"raw": "SyntheticEvent<\n $ReadOnly<{|\n value: boolean,\n |}>,\n>"
}
}
],
"return": {
"name": "union",
"raw": "Promise<void> | void",
"elements": [
{
"name": "Promise",
"elements": [
{
"name": "void"
}
],
"raw": "Promise<void>"
},
{
"name": "void"
}
]
}
},
"nullable": true
},
"description": "Called when the user tries to change the value of the switch.\n\nReceives the change event as an argument. If you want to only receive the\nnew value, use `onValueChange` instead."
},
"onValueChange": {
"required": false,
"flowType": {
"name": "signature",
"type": "function",
"raw": "(value: boolean) => Promise<void> | void",
"signature": {
"arguments": [
{
"name": "value",
"type": {
"name": "boolean"
}
}
],
"return": {
"name": "union",
"raw": "Promise<void> | void",
"elements": [
{
"name": "Promise",
"elements": [
{
"name": "void"
}
],
"raw": "Promise<void>"
},
{
"name": "void"
}
]
}
},
"nullable": true
},
"description": "Called when the user tries to change the value of the switch.\n\nReceives the new value as an argument. If you want to instead receive an\nevent, use `onChange`."
}
},
"composes": [
"ViewProps"
]
}
]
1 change: 1 addition & 0 deletions package.json
View file
Expand Up @@ -150,6 +150,7 @@
"react": "16.9.0",
"react-test-renderer": "16.9.0",
"shelljs": "^0.7.8",
"signedsource": "^1.0.0",
"ws": "^6.1.4",
"yargs": "^9.0.0"
},
Expand Down
90 changes: 90 additions & 0 deletions scripts/generate-api-docs.js
View file
@@ -0,0 +1,90 @@
#!/usr/bin/env node
/**
* Copyright (c) Facebook, Inc. and its affiliates.
*
* This source code is licensed under the MIT license found in the
* LICENSE file in the root directory of this source tree.
*
* @format
*/

'use strict';

const SignedSource = require('signedsource');
const fs = require('fs');
const glob = require('glob');
const path = require('path');
const reactDocs = require('react-docgen');

const GENERATE_ANNOTATION = '@' + 'generate-docs';
const RN_ROOT = path.join(__dirname, '..');
const OUTPUT_PATH = path.join(RN_ROOT, 'docs', 'generatedComponentApiDocs.js');

const TEMPLATE = `/**
* Copyright (c) Facebook, Inc. and its affiliates.
*
* This source code is licensed under the MIT license found in the
* LICENSE file in the root directory of this source tree.
*
* This file is used by the React Native website to show the props of core components
* This file was generated by running scripts/generate-api-docs.js
*
* ::_SIGNING_TOKEN_::
*/
'use strict';
module.exports = ::_CONTENT_::
`;

const allComponentFiles = glob.sync(
path.join(RN_ROOT, '/Libraries/Components/**/*.js'),
{
nodir: true,
},
);

const docs = allComponentFiles.reduce((acc, file) => {
const contents = fs.readFileSync(file, {encoding: 'utf-8'});
if (!contents.includes(GENERATE_ANNOTATION)) {
return acc;
}

const result = reactDocs.parse(
contents,
reactDocs.resolver.findExportedComponentDefinition,
);

acc.push(cleanComponentResult(result));

return acc;
}, []);

const content = TEMPLATE.replace(
'::_CONTENT_::',
JSON.stringify(docs, null, 2),
).replace('::_SIGNING_TOKEN_::', SignedSource.getSigningToken());

const signedContent = SignedSource.signFile(content);

if (process.env.NODE_ENV === 'test') {
const existingContent = fs.readFileSync(OUTPUT_PATH, 'utf8');
if (signedContent !== existingContent) {
console.error(
path.relative(RN_ROOT, OUTPUT_PATH),
'is not up to date. Run',
'scripts/generate-api-docs.js',
'to regenerate the file.',
);
process.exit(1);
}
} else {
fs.writeFileSync(OUTPUT_PATH, SignedSource.signFile(content));
}

function cleanComponentResult(component) {
return {
...component,
methods: component.methods.filter(method => !method.name.startsWith('_')),
};
}
5 changes: 5 additions & 0 deletions yarn.lock
View file
Expand Up @@ -6418,6 +6418,11 @@ signal-exit@^3.0.0, signal-exit@^3.0.2:
resolved "https://registry.yarnpkg.com/signal-exit/-/signal-exit-3.0.2.tgz#b5fdc08f1287ea1178628e415e25132b73646c6d"
integrity sha1-tf3AjxKH6hF4Yo5BXiUTK3NkbG0=

signedsource@^1.0.0:
version "1.0.0"
resolved "https://registry.yarnpkg.com/signedsource/-/signedsource-1.0.0.tgz#1ddace4981798f93bd833973803d80d52e93ad6a"
integrity sha1-HdrOSYF5j5O9gzlzgD2A1S6TrWo=

simple-plist@^1.0.0:
version "1.0.0"
resolved "https://registry.yarnpkg.com/simple-plist/-/simple-plist-1.0.0.tgz#bed3085633b22f371e111f45d159a1ccf94b81eb"
Expand Down

0 comments on commit eb7dbc8

Please sign in to comment.