Prettify docs files (#2275)

Summary: **Summary** Prettier can also be used to format more than just JS files, it can format Markdown files too. Instead of using Flow parser for all files in `prettier.config.js`, we can just limit Flow parser for JS files and let Prettier find the default parsers for the various file formats. Hence I tweaked the Prettier config and added overrides for: - JS format - Use Flow parser - Markdown format - Restrict to 80 characters so that it's easier to read I then ran Prettier on all the docs. I've added a `prettier:diff` command into the `lint-docs` step, ran alongside with Alex that will fail when there are unformatted docs. It's not part of the CI step as I think that might be a bit too strict given that some people (including myself) edit docs in the GitHub UI and that might cause formatting issues which can be fixed by running the `format-docs` command every now and then. The formatting is only restricted to the docs now and not code as it's potentially dangerous to format code that gets synced with internal FB repos. **Test Plan** Load website. Pull Request resolved: #2275 Reviewed By: mrkev Differential Revision: D18807420 Pulled By: yangshun fbshipit-source-id: b3f34282c2a2cad8e89cd90e8f3f6b3860b747fc
facebookarchive · Dec 16, 2019 · 6fc9964 · 6fc9964
1 parent 5d37c03
commit 6fc9964
Show file tree

Hide file tree

Showing 23 changed files with 210 additions and 191 deletions.
diff --git a/docs/APIReference-APIMigration.md b/docs/APIReference-APIMigration.md
@@ -11,9 +11,9 @@ to the `ContentState` record.
 
 This API improvement unlocks the path for many benefits that will be available in v0.11:
 
-* DraftEntity instances and storage will be immutable.
-* DraftEntity will no longer be globally accessible.
-* Any changes to entity data will trigger a re-render.
+- DraftEntity instances and storage will be immutable.
+- DraftEntity will no longer be globally accessible.
+- Any changes to entity data will trigger a re-render.
 
 ## Quick Overview
 
@@ -24,21 +24,15 @@ Here is a quick list of what has been changed and how to update your application
 **Old Syntax**
 
 ```js
-const entityKey = Entity.create(
-  urlType,
-  'IMMUTABLE',
-  {src: urlValue},
-);
+const entityKey = Entity.create(urlType, 'IMMUTABLE', {src: urlValue});
 ```
 
 **New Syntax**
 
 ```js
-const contentStateWithEntity = contentState.createEntity(
-  urlType,
-  'IMMUTABLE',
-  {src: urlValue},
-);
+const contentStateWithEntity = contentState.createEntity(urlType, 'IMMUTABLE', {
+  src: urlValue,
+});
 const entityKey = contentStateWithEntity.getLastCreatedEntityKey();
 ```
 
@@ -65,7 +59,8 @@ const entityInstance = contentState.getEntity(entityKey);
 ```js
 const compositeDecorator = new CompositeDecorator([
   {
-    strategy: (contentBlock, callback) => exampleFindTextRange(contentBlock, callback),
+    strategy: (contentBlock, callback) =>
+      exampleFindTextRange(contentBlock, callback),
     component: ExampleTokenComponent,
   },
 ]);
@@ -76,36 +71,31 @@ const compositeDecorator = new CompositeDecorator([
 ```js
 const compositeDecorator = new CompositeDecorator([
   {
-    strategy: (
-      contentBlock,
-      callback,
-      contentState
-    ) => exampleFindTextRange(contentBlock, callback, contentState),
+    strategy: (contentBlock, callback, contentState) => (
+      contentBlock, callback, contentState
+    ),
     component: ExampleTokenComponent,
   },
 ]);
 ```
 
 Note that ExampleTokenComponent will receive contentState as a prop.
 
-Why does the 'contentState' get passed into the decorator strategy now? Because we may need it if our strategy is to  find certain entities in the contentBlock:
+Why does the 'contentState' get passed into the decorator strategy now? Because we may need it if our strategy is to find certain entities in the contentBlock:
 
 ```js
 const mutableEntityStrategy = function(contentBlock, callback, contentState) {
-  contentBlock.findEntityRanges(
-    (character) => {
-      const entityKey = character.getEntity();
-      if (entityKey === null) {
-        return false;
-      }
-      // To look for certain types of entities,
-      // or entities with a certain mutability,
-      // you may need to get the entity from contentState.
-      // In this example we get only mutable entities.
-      return contentState.getEntity(entityKey).getMutability() === 'MUTABLE';
-    },
-    callback,
-  );
+  contentBlock.findEntityRanges(character => {
+    const entityKey = character.getEntity();
+    if (entityKey === null) {
+      return false;
+    }
+    // To look for certain types of entities,
+    // or entities with a certain mutability,
+    // you may need to get the entity from contentState.
+    // In this example we get only mutable entities.
+    return contentState.getEntity(entityKey).getMutability() === 'MUTABLE';
+  }, callback);
 };
 ```
 
@@ -115,34 +105,25 @@ const mutableEntityStrategy = function(contentBlock, callback, contentState) {
 
 ```js
 function findLinkEntities(contentBlock, callback) {
-  contentBlock.findEntityRanges(
-    (character) => {
-      const entityKey = character.getEntity();
-      return (
-        entityKey !== null &&
-        Entity.get(entityKey).getType() === 'LINK'
-      );
-    },
-    callback,
-  );
-};
+  contentBlock.findEntityRanges(character => {
+    const entityKey = character.getEntity();
+    return entityKey !== null && Entity.get(entityKey).getType() === 'LINK';
+  }, callback);
+}
 ```
 
 **New Syntax**
 
 ```js
 function findLinkEntities(contentBlock, callback, contentState) {
-  contentBlock.findEntityRanges(
-    (character) => {
-      const entityKey = character.getEntity();
-      return (
-        entityKey !== null &&
-        contentState.getEntity(entityKey).getType() === 'LINK'
-      );
-    },
-    callback,
-  );
-};
+  contentBlock.findEntityRanges(character => {
+    const entityKey = character.getEntity();
+    return (
+      entityKey !== null &&
+      contentState.getEntity(entityKey).getType() === 'LINK'
+    );
+  }, callback);
+}
 ```
 
 ## More Information

diff --git a/docs/APIReference-CharacterMetadata.md b/docs/APIReference-CharacterMetadata.md
@@ -26,7 +26,7 @@ for information on how `CharacterMetadata` is used within `ContentBlock`.
 
 ## Overview
 
-*Static Methods*
+_Static Methods_
 
 <ul class="apiIndex">
   <li>
@@ -51,7 +51,7 @@ for information on how `CharacterMetadata` is used within `ContentBlock`.
   </li>
 </ul>
 
-*Methods*
+_Methods_
 
 <ul class="apiIndex">
   <li>

diff --git a/docs/APIReference-ContentBlock.md b/docs/APIReference-ContentBlock.md
@@ -7,29 +7,29 @@ title: ContentBlock
 [Record](http://facebook.github.io/immutable-js/docs/#/Record/Record) that
 represents the full state of a single block of editor content, including:
 
-  - Plain text contents of the block
-  - Type, e.g. paragraph, header, list item
-  - Entity, inline style, and depth information
+- Plain text contents of the block
+- Type, e.g. paragraph, header, list item
+- Entity, inline style, and depth information
 
 A `ContentState` object contains an `OrderedMap` of these `ContentBlock` objects,
 which together comprise the full contents of the editor.
 
 `ContentBlock` objects are largely analogous to block-level HTML elements like
 paragraphs and list items. The available types are:
 
-  - unstyled
-  - paragraph
-  - header-one
-  - header-two
-  - header-three
-  - header-four
-  - header-five
-  - header-six
-  - unordered-list-item
-  - ordered-list-item
-  - blockquote
-  - code-block
-  - atomic
+- unstyled
+- paragraph
+- header-one
+- header-two
+- header-three
+- header-four
+- header-five
+- header-six
+- unordered-list-item
+- ordered-list-item
+- blockquote
+- code-block
+- atomic
 
 New `ContentBlock` objects may be created directly using the constructor.
 Expected Record values are detailed below.
@@ -54,7 +54,7 @@ supplied text.
 
 ## Overview
 
-*Methods*
+_Methods_
 
 <ul class="apiIndex">
   <li>
@@ -114,7 +114,7 @@ supplied text.
   </li>
 </ul>
 
-*Properties*
+_Properties_
 
 > Note
 >
@@ -161,13 +161,15 @@ supplied text.
 ```js
 getKey(): string
 ```
+
 Returns the string key for this `ContentBlock`. Block keys are alphanumeric string. It is recommended to use `generateRandomKey` to generate block keys.
 
 ### `getType()`
 
 ```js
 getType(): DraftBlockType
 ```
+
 Returns the type for this `ContentBlock`. Type values are largely analogous to
 block-level HTML elements.
 
@@ -176,6 +178,7 @@ block-level HTML elements.
 ```js
 getText(): string
 ```
+
 Returns the full plaintext for this `ContentBlock`. This value does not contain
 any styling, decoration, or HTML information.
 
@@ -204,6 +207,7 @@ This value uses the standard JavaScript `length` property for the string, and is
 ```js
 getDepth(): number
 ```
+
 Returns the depth value for this block, if any. This is currently used only for list items.
 
 ### `getInlineStyleAt()`

diff --git a/docs/APIReference-ContentState.md b/docs/APIReference-ContentState.md
@@ -18,7 +18,7 @@ objects.
 
 ## Overview
 
-*Static Methods*
+_Static Methods_
 
 <ul class="apiIndex">
   <li>
@@ -33,7 +33,7 @@ objects.
   </li>
 </ul>
 
-*Methods*
+_Methods_
 
 <ul class="apiIndex">
   <li>
@@ -138,7 +138,7 @@ objects.
   </li>
 </ul>
 
-*Properties*
+_Properties_
 
 > Use [Immutable Map API](http://facebook.github.io/immutable-js/docs/#/Map) to
 > set properties.
@@ -148,7 +148,10 @@ objects.
 > ```js
 > const editorState = EditorState.createEmpty();
 > const contentState = editorState.getCurrentContent();
-> const contentStateWithSelectionBefore = contentState.set('selectionBefore', SelectionState.createEmpty(contentState.getBlockForKey('1pu4d')));
+> const contentStateWithSelectionBefore = contentState.set(
+>   'selectionBefore',
+>   SelectionState.createEmpty(contentState.getBlockForKey('1pu4d')),
+> );
 > ```
 
 <ul class="apiIndex">
@@ -205,7 +208,7 @@ getEntityMap(): EntityMap
 ```
 
 Returns an object store containing all `DraftEntity` records that have been
-created.  In upcoming v0.11.0 the map returned will be an Immutable ordered map
+created. In upcoming v0.11.0 the map returned will be an Immutable ordered map
 of `DraftEntity` records.
 
 In most cases, you should be able to use the convenience methods below to target

diff --git a/docs/APIReference-Data-Conversion.md b/docs/APIReference-Data-Conversion.md
@@ -41,7 +41,6 @@ Given a `ContentState` object, convert it to a raw JS structure. This is useful
 when saving an editor state for storage, conversion to other formats, or
 other usage within an application.
 
-
 ### `convertFromHTML()`
 
 ```js
@@ -52,7 +51,7 @@ const sampleMarkup =
 const blocksFromHTML = convertFromHTML(sampleMarkup);
 const state = ContentState.createFromBlockArray(
   blocksFromHTML.contentBlocks,
-  blocksFromHTML.entityMap
+  blocksFromHTML.entityMap,
 );
 
 this.state = {

diff --git a/docs/APIReference-Editor.md b/docs/APIReference-Editor.md
@@ -16,7 +16,7 @@ See [API Basics](/docs/quickstart-api-basics) for an introduction.
 ### `editorState`
 
 ```js
-editorState: EditorState
+editorState: EditorState;
 ```
 
 The `EditorState` object to be rendered by the `Editor`.
@@ -84,6 +84,7 @@ Optionally set a function to define custom block rendering. See [Advanced Topics
 ```js
 blockRendererMap?: DraftBlockRenderMap
 ```
+
 Provide a map of block rendering configurations. Each block type maps to element tag and an optional react element wrapper. This configuration is used for both rendering and paste processing. See
 [Advanced Topics: Custom Block Rendering](/docs/advanced-topics-custom-block-render-map) for details on usage.
 
@@ -248,7 +249,7 @@ handleBeforeInput?: (
 Handle the characters to be inserted from a `beforeInput` event. Returning `'handled'`
 causes the default behavior of the `beforeInput` event to be prevented (i.e. it is
 the same as calling the `preventDefault` method on the event).
-Example usage: After a user has typed `- ` at the start of a new block, you might
+Example usage: After a user has typed `-` at the start of a new block, you might
 convert that `ContentBlock` into an `unordered-list-item`.
 
 At Facebook, we also use this to convert typed ASCII quotes into "smart" quotes,