Skip to content

chore: prepare docs for Docusaurus v3 upgrade - 1st iteration #3807

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Simek merged 44 commits into from
Aug 17, 2023
Merged

chore: prepare docs for Docusaurus v3 upgrade - 1st iteration #3807

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
44 commits
Select commit Hold shift + click to select a range
917cfbf
basic docs prep changes
slorber Jul 28, 2023
e23a556
prettier docs
slorber Jul 28, 2023
3630b24
Review: fix Android version <5 with HTML code
slorber Aug 3, 2023
589fc5f
New architecture appendix tables: use HTML code consistently
slorber Aug 3, 2023
d762c97
Add explicit code block languages
slorber Aug 3, 2023
e76988b
Review: update issue/commit message placeholder syntax by [VAR]
slorber Aug 3, 2023
4b13f22
fix clean => clear typo
slorber Aug 4, 2023
31d228e
POC of using markdown links inside code blocks
slorber Aug 4, 2023
da5b845
useless flatMap
slorber Aug 4, 2023
593b0d1
use inline code blocks on JS env page
slorber Aug 4, 2023
a96910d
Merge branch 'main' into slorber/docs-preparation-docusaurus-v3
slorber Aug 17, 2023
6bcdb4d
remove useless doc
slorber Aug 17, 2023
f86ef83
backport docs change
slorber Aug 17, 2023
1ed6b18
backport docs change
slorber Aug 17, 2023
4688149
backport docs change
slorber Aug 17, 2023
490ad51
backport docs change
slorber Aug 17, 2023
1bf5b58
backport docs change
slorber Aug 17, 2023
866e651
backport docs change
slorber Aug 17, 2023
57f7b91
backport docs change
slorber Aug 17, 2023
2119349
backport docs change
slorber Aug 17, 2023
ee0fb64
backport docs change
slorber Aug 17, 2023
c102920
backport docs change
slorber Aug 17, 2023
37a9d7a
backport docs change
slorber Aug 17, 2023
9d7ead8
backport docs change
slorber Aug 17, 2023
5f18f23
backport docs change
slorber Aug 17, 2023
1035887
backport docs change
slorber Aug 17, 2023
9bae1ca
backport docs change
slorber Aug 17, 2023
61ab5aa
backport docs change
slorber Aug 17, 2023
1267a3a
backport docs change
slorber Aug 17, 2023
7941e7f
backport docs change
slorber Aug 17, 2023
16d2049
backport docs change
slorber Aug 17, 2023
bf4e31b
backport docs change
slorber Aug 17, 2023
c014092
backport docs change
slorber Aug 17, 2023
ef20fa8
backport docs change
slorber Aug 17, 2023
b23022c
backport docs change
slorber Aug 17, 2023
76f0132
backport docs change
slorber Aug 17, 2023
1fe1364
backport docs change
slorber Aug 17, 2023
08bcb5e
backport docs change
slorber Aug 17, 2023
6cbc79f
backport docs change
slorber Aug 17, 2023
aa0044d
backport docs change
slorber Aug 17, 2023
679b311
remove .md extension in colors
slorber Aug 17, 2023
c2660fe
Use fullwidth vertical line instead of pipe
slorber Aug 17, 2023
bd4e036
Improve sendIntent extra param type
slorber Aug 17, 2023
dd3e2a6
remove console log comments
slorber Aug 17, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 0 additions & 1 deletion docs/_getting-started-macos-ios.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,3 @@
import Anchor from './Anchor.jsx';
Comment thread
Simek marked this conversation as resolved.
import RemoveGlobalCLI from './\_remove-global-cli.md';
import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; import constants from '@site/core/TabsConstants';

Expand Down
2 changes: 1 addition & 1 deletion docs/_integration-with-existing-apps-java.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -264,7 +264,7 @@ protected void onActivityResult(int requestCode, int resultCode, Intent data) {

Let's add some native code in order to start the React Native runtime and tell it to render our JS component. To do this, we're going to create an `Activity` that creates a `ReactRootView`, starts a React application inside it and sets it as the main content view.

> If you are targeting Android version <5, use the `AppCompatActivity` class from the `com.android.support:appcompat` package instead of `Activity`.
> If you are targeting Android version &lt;5, use the `AppCompatActivity` class from the `com.android.support:appcompat` package instead of `Activity`.

```java
public class MyReactActivity extends Activity implements DefaultHardwareBackBtnHandler {
Expand Down
2 changes: 1 addition & 1 deletion docs/_integration-with-existing-apps-kotlin.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -265,7 +265,7 @@ override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent?)

Let's add some native code in order to start the React Native runtime and tell it to render our JS component. To do this, we're going to create an `Activity` that creates a `ReactRootView`, starts a React application inside it and sets it as the main content view.

> If you are targeting Android version <5, use the `AppCompatActivity` class from the `com.android.support:appcompat` package instead of `Activity`.
> If you are targeting Android version &lt;5, use the `AppCompatActivity` class from the `com.android.support:appcompat` package instead of `Activity`.

```kotlin
class MyReactActivity : Activity(), DefaultHardwareBackBtnHandler {
Expand Down
6 changes: 3 additions & 3 deletions docs/animated.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -463,9 +463,9 @@ Animations are started by calling start() on your animation. start() takes a com

**Parameters:**

| Name | Type | Required | Description |
| -------- | ------------------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| callback | (result: {finished: boolean}) => void | No | Function that will be called after the animation finished running normally or when the animation is done because stop() was called on it before it could finish |
| Name | Type | Required | Description |
| -------- | --------------------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| callback | `(result: {finished: boolean}) => void` | No | Function that will be called after the animation finished running normally or when the animation is done because stop() was called on it before it could finish |
Comment thread
Simek marked this conversation as resolved.

Start example with callback:

Expand Down
12 changes: 6 additions & 6 deletions docs/animatedvaluexy.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -74,9 +74,9 @@ Directly set the value. This will stop any animations running on the value and u

**Parameters:**

| Name | Type | Required | Description |
| ----- | ---------------------- | -------- | ----------- |
| value | {x: number; y: number} | Yes | Value |
| Name | Type | Required | Description |
| ----- | ------------------------ | -------- | ----------- |
| value | `{x: number; y: number}` | Yes | Value |

---

Expand All @@ -90,9 +90,9 @@ Sets an offset that is applied on top of whatever value is set, whether via `set

**Parameters:**

| Name | Type | Required | Description |
| ------ | ---------------------- | -------- | ------------ |
| offset | {x: number; y: number} | Yes | Offset value |
| Name | Type | Required | Description |
| ------ | ------------------------ | -------- | ------------ |
| offset | `{x: number; y: number}` | Yes | Offset value |

---

Expand Down
6 changes: 3 additions & 3 deletions docs/button.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -120,9 +120,9 @@ export default App;

Handler to be called when the user taps the button.

| Type |
| ----------------------------------------- |
| ({nativeEvent: [PressEvent](pressevent)}) |
| Type |
| ---------------------------------------------- |
| `md ({nativeEvent: [PressEvent](pressevent)})` |

@slorber slorber Aug 4, 2023

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@cipolleschi @Simek @cortinico

This new inline code syntax

`md ({nativeEvent: [PressEvent](pressevent)})`

Turns on a basic support for Markdown links inside

CleanShot 2023-08-04 at 17 46 24

Can you validate this idea?

IMHO this is an UX improvement, considering it's code it should be an inline code block. The non-usage of links before was probably a technical limitation that this new solution enables.

But this requires to teach technical writers to use the `md prefix to turn it on. Considering the current implementation, I prefer to keep it opt-in instead of applied everywhere by default.

Review links:

@cipolleschi cipolleschi Aug 8, 2023

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I like it. I don't think that it will be an issue: if a technical writer wants to achieve the same result in these pages, it will likely go here and see how that was achieved and then it will copy the syntax!


---

Expand Down
6 changes: 3 additions & 3 deletions docs/flatlist.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -618,9 +618,9 @@ If provided, a standard RefreshControl will be added for "Pull to Refresh" funct

Called when the viewability of rows changes, as defined by the `viewabilityConfig` prop.

| Type |
| ------------------------------------------------------------------------------------------------ |
| (callback: {changed: [ViewToken](viewtoken)[], viewableItems: [ViewToken](viewtoken)[]} => void; |
| Type |
| ----------------------------------------------------------------------------------------------------- |
| `md (callback: {changed: [ViewToken](viewtoken)[], viewableItems: [ViewToken](viewtoken)[]} => void;` |

---

Expand Down
12 changes: 6 additions & 6 deletions docs/image.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -244,9 +244,9 @@ Invoked on load error.

Invoked on mount and on layout changes.

| Type |
| ------------------------------------------------- |
| ({nativeEvent: [LayoutEvent]layoutevent)} => void |
| Type |
| ------------------------------------------------------- |
| `md ({nativeEvent: [LayoutEvent](layoutevent)} => void` |

---

Expand All @@ -256,9 +256,9 @@ Invoked when load completes successfully.

**Example:** `onLoad={({nativeEvent: {source: {width, height}}}) => setImageRealSize({width, height})}`

| Type |
| ------------------------------------------------------------- |
| ({nativeEvent: [ImageLoadEvent]image#imageloadevent)} => void |
| Type |
| ------------------------------------------------------------------- |
| `md ({nativeEvent: [ImageLoadEvent](image#imageloadevent)} => void` |

---

Expand Down
20 changes: 10 additions & 10 deletions docs/javascript-environment.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -84,25 +84,25 @@ Many standard functions are also available on all the supported JavaScript runti

#### Browser

- [CommonJS require](https://nodejs.org/docs/latest/api/modules.html)
- [console.{log, warn, error, info, trace, table, group, groupEnd}](https://developer.chrome.com/devtools/docs/console-api)
- [XMLHttpRequest, fetch](network.md#content)
- [{set, clear}{Timeout, Interval, Immediate}, {request, cancel}AnimationFrame](timers.md#content)
- [CommonJS `require`](https://nodejs.org/docs/latest/api/modules.html)
- `md [console.{log, warn, error, info, trace, table, group, groupEnd}](https://developer.chrome.com/devtools/docs/console-api)`
- [`XMLHttpRequest`, `fetch`](network.md#content)
- [`{set, clear}{Timeout, Interval, Immediate}, {request, cancel}AnimationFrame`](timers.md#content)

#### ECMAScript 2015 (ES6)

- [Array.from](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/from)
- Array.prototype.{[find](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/find), [findIndex](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/findIndex)}
- [Object.assign](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/assign)
- String.prototype.{[startsWith](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/startsWith), [endsWith](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/endsWith), [repeat](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/repeat), [includes](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/includes)}
- [`Array.from`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/from)
- `md Array.prototype.{[find](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/find), [findIndex](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/findIndex)}`
- [`Object.assign`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/assign)
- `md String.prototype.{[startsWith](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/startsWith), [endsWith](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/endsWith), [repeat](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/repeat), [includes](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/includes)}`

#### ECMAScript 2016 (ES7)

- Array.prototype.[includes](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/includes)
- `md Array.prototype.[includes](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/includes)`

#### ECMAScript 2017 (ES8)

- Object.{[entries](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/entries), [values](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/values)}
- `md Object.{[entries](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/entries), [values](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/values)}`
Comment on lines -87 to +105

@slorber slorber Aug 4, 2023 •
edited
Loading

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@cipolleschi , in reply to your comment

On this page, if we start using inline code blocks, then it's not always clear how to keep it consistent without modifying a bit the content:

  • Should the link wrap the inline code block? (only possible in some cases)
  • Should the link be inside the inline code block? (needed if there's more than 1 link, cf Array.prototype.{xLink,yLink})

To understand better the visual consistency problem:

Before: https://reactnative.dev/docs/next/javascript-environment#polyfills

CleanShot 2023-08-04 at 18 19 18@2x

After: https://deploy-preview-3807--react-native.netlify.app/docs/next/javascript-environment#polyfills

CleanShot 2023-08-04 at 18 22 03@2x

As you can see, it does not visually render exactly the same depending on the order in which you apply the link/inline-code-block, and with current content shape, it's not really possible consistently one pattern or the other (or you would have to use code blocks for things that are not actually code: CommonJS require, XMLHttpRequest, fetch)

Is this consistency problem a blocker, or can we still merge this PR?

It can also be possible to modify the content itself to make it more consistent, because in some cases we have one link to a whole API (console), and sometimes we link to individual functions (Array methods).

In {set, clear}{Timeout, Interval, Immediate}, {request, cancel}AnimationFrame it's quite hard to know where to apply inline code blocks 😅 Note the , in the middle is not code.


#### Specific

Expand Down
8 changes: 4 additions & 4 deletions docs/linking.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -651,7 +651,7 @@ Launch an Android intent with extras.

**Parameters:**

| Name | Type |
| ----------------------------------------------------------- | ------------------------------------------------------------ |
| action <div className="label basic required">Required</div> | string |
| extras | array of `{key: string, value: string \| number \| boolean}` |
| Name | Type |
| ----------------------------------------------------------- | ---------------------------------------------------------- |
| action <div className="label basic required">Required</div> | string |
| extras | `Array<{key: string, value: string ｜ number ｜ boolean}>` |
32 changes: 16 additions & 16 deletions docs/new-architecture-appendix.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -38,9 +38,9 @@ This is recommended over using plain `Object`, for type safety.

**Example:** `{| foo: string, ... |}`

| Nullable Support? | Android (Java) | iOS |
| --------------------------------------------- | -------------- | --- |
| <code>?{&#124; foo: string, ...&#124;}</code> | - | - |
| Nullable Support? | Android (Java) | iOS |
| ------------------------------------------------------- | -------------- | --- |
| <code>?&#123;&#124; foo: string, ...&#124;&#125;</code> | - | - |

### `Object`

Expand Down Expand Up @@ -98,19 +98,19 @@ You may also find it useful to refer to the JavaScript specifications for the co

You may use the following table as a reference for which types are supported and what they map to in each platform:

| TypeScript Type | Nullable Support? | Android (Java) | iOS | Note |
| ---------------------------------------------- | -------------------------------------------------------- | ------------------------------------ | -------------------------------------------------------------- | ------------------------------------------------------------------------------ |
| `string` | <code>string &#124; null </code> | `String` | `NSString` | |
| `boolean` | <code>boolean &#124; null </code> | `Boolean` | `NSNumber` | |
| `number` | No | `double` | `NSNumber` | |
| <code>{&#124; foo: string, ... &#124;}</code> | <code>{&#124; foo: string, ...&#124;} &#124; null</code> | | | Object literal. This is recommended over simply using Object, for type safety. |
| `Object` | <code>Object &#124; null </code> | `ReadableMap` | `@{} (untyped dictionary)` | Recommended to use object literal (see above). |
| `Array<*>` | <code>Array<\*> &#124; null </code> | `ReadableArray` | `NSArray` (or `RCTConvertVecToArray` when used inside objects) | |
| `Function` | <code>Function &#124; null </code> | | | |
| `Promise<*>` | <code>Promise<\*> &#124; null </code> | `com.facebook.react.bridge.Promise` | `RCTPromiseResolve` and `RCTPromiseRejectBlock` | |
| Type aliases of the above | Yes | | | |
| Type Unions <code>'SUCCESS'&#124;'FAIL'</code> | Only as callbacks. | | | Type unions only supported as callbacks. |
| Callbacks: `( ) =>` | Yes | `com.facebook.react.bridge.Callback` | `RCTResponseSenderBlock` | Callback functions are not type checked, and are generalized as Objects. |
| TypeScript Type | Nullable Support? | Android (Java) | iOS | Note |
| ------------------------------------------------------- | ------------------------------------------------------------------ | ------------------------------------ | -------------------------------------------------------------- | ------------------------------------------------------------------------------ |
| `string` | <code>string &#124; null </code> | `String` | `NSString` | |
| `boolean` | <code>boolean &#124; null </code> | `Boolean` | `NSNumber` | |
| `number` | No | `double` | `NSNumber` | |
| <code>&#123;&#124; foo: string, ... &#124;&#125;</code> | <code>&#123;&#124; foo: string, ...&#124;&#125; &#124; null</code> | | | Object literal. This is recommended over simply using Object, for type safety. |
| `Object` | <code>Object &#124; null </code> | `ReadableMap` | `@{} (untyped dictionary)` | Recommended to use object literal (see above). |
| `Array<*>` | <code>Array&#60;\*> &#124; null </code> | `ReadableArray` | `NSArray` (or `RCTConvertVecToArray` when used inside objects) | |
| `Function` | <code>Function &#124; null </code> | | | |
| `Promise<*>` | <code>Promise&#60;\*> &#124; null </code> | `com.facebook.react.bridge.Promise` | `RCTPromiseResolve` and `RCTPromiseRejectBlock` | |
| Type aliases of the above | Yes | | | |
| Type Unions <code>'SUCCESS'&#124;'FAIL'</code> | Only as callbacks. | | | Type unions only supported as callbacks. |
| Callbacks: `( ) =>` | Yes | `com.facebook.react.bridge.Callback` | `RCTResponseSenderBlock` | Callback functions are not type checked, and are generalized as Objects. |

You may also find it useful to refer to the JavaScript specifications for the core modules in React Native. These are located inside the `Libraries/` directory in the React Native repository.

Expand Down
Loading