Skip to content

Rewrite the docs #1052

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.

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

Draft
wants to merge 52 commits into
base: main
Choose a base branch
from
Draft
Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
52 commits
Select commit Hold shift + click to select a range
d0e3628
`Archmonger/reactpy-docs/main` to `reactive-python/reactpy/new-docs`
Archmonger Jun 14, 2023
8602fff
add gh pages publishing workflow
Archmonger Jun 14, 2023
b05c29c
fix requirements path
Archmonger Jun 14, 2023
3b5341a
update github pages link
Archmonger Jun 14, 2023
2b5dd4d
update site description
Archmonger Jun 15, 2023
8cc75aa
minor typos
Archmonger Jun 16, 2023
a05cbe0
setup for the tutorial section
Archmonger Jun 16, 2023
2f5b68a
switch from abstract to note admonitiion
Archmonger Jun 16, 2023
308d216
reword note
Archmonger Jun 16, 2023
838671b
cell-var-from-loop
Archmonger Jun 18, 2023
58bac05
update readme
Archmonger Jun 19, 2023
ad10c29
add padding to sidebar nav
Archmonger Jun 19, 2023
73dadc9
Inspecting the starter code
Archmonger Jun 19, 2023
f28a6ab
Add disclaimer about unfinished pages
Archmonger Jun 19, 2023
60d54e0
rename tic-tac-toe folder
Archmonger Jun 19, 2023
0a347dd
add styling utils
Archmonger Jun 19, 2023
acf3f5c
build a static version in React
Archmonger Jun 19, 2023
e4be299
Find the minimal but complete representation of UI state
Archmonger Jun 19, 2023
067279f
Identify where your state should live
Archmonger Jun 19, 2023
3a0d107
Thinking in React
Archmonger Jun 19, 2023
865c18f
Add fixme
Archmonger Jun 19, 2023
6195050
start a new react project
Archmonger Jun 19, 2023
fa4b1df
Add in progress warnings
Archmonger Jun 19, 2023
3c0b071
Add more in progress warnings
Archmonger Jun 19, 2023
ce60b29
a little bit of the "responding to events" section
Archmonger Jun 20, 2023
656623a
remove start from the runnable examples
Archmonger Jun 20, 2023
3c644cc
more in progress warnings
Archmonger Jun 20, 2023
fe45c54
add stub docs for hooks
Archmonger Jun 20, 2023
3de3fd3
add use-id warning
Archmonger Jun 20, 2023
3aab58b
Add undeveloped hooks
Archmonger Jun 20, 2023
8f58f8c
mkdocs-section-index: Move titles to mkdocs.yml
Archmonger Jun 21, 2023
c2c0281
verbiage on installation docs
Archmonger Jun 21, 2023
aec77d4
add installation index page
Archmonger Jun 21, 2023
7c68a47
editor setup
Archmonger Jun 21, 2023
302f133
remove unneeded space
Archmonger Jun 21, 2023
11aa58a
format everything
Archmonger Jun 21, 2023
ab653c5
Add extras section
Archmonger Jun 27, 2023
64432b2
Cleanup blocked pages
Archmonger Jun 30, 2023
260b5e5
change undeveloped warning text
Archmonger Jun 30, 2023
1ffc0d9
add pyscript backend
Archmonger Jul 13, 2023
106a128
add mike
Archmonger Aug 27, 2023
b505d03
sync styles to django
Archmonger Aug 27, 2023
c9964f6
Change you will learn" capitalization
Archmonger Aug 28, 2023
5ed1300
Change note to abstract
Archmonger Jan 5, 2024
0a36534
html can now return none
Archmonger Jan 5, 2024
2bef10d
unbork large portions of the theme
Archmonger Mar 14, 2025
169e33e
delete python src from this branch
Archmonger Mar 14, 2025
fb84879
ReactPy V2 changes
Archmonger Mar 15, 2025
1e93576
fix a few pages
Archmonger Mar 15, 2025
5ee7998
add tools and packages section, remove outdated references, and fix J…
Archmonger Mar 16, 2025
30b6654
refine tutorial instructions and update language for clarity
Archmonger Mar 16, 2025
b295d7b
bump gitignore
Archmonger Jun 15, 2025
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
Prev Previous commit
Next Next commit
more in progress warnings
  • Loading branch information
Archmonger committed Jun 20, 2023
commit 3c644cc3a50f96e0051a4e2e97c2662ccdc8563b
12 changes: 6 additions & 6 deletions docs/src/learn/add-react-to-an-existing-project.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,12 @@
title: Add React to an Existing Project 🚫
---

!!! warning "In Progress"

This feature is planned, but not yet developed.

See [this issue](https://github.com/reactive-python/reactpy/issues/653) for more details.

## Overview

<p class="intro" markdown>
Expand All @@ -10,12 +16,6 @@ If you want to add some interactivity to your existing project, you don't have t

</p>

!!! warning "In Progress"

This feature is planned, but not yet developed.

See [this issue](https://github.com/reactive-python/reactpy/issues/653) for more details.

<!--
<Note>

Expand Down
11 changes: 9 additions & 2 deletions docs/src/learn/python-in-psx-with-curly-braces.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,13 @@
---
title: Python in PSX with Curly Braces 🚧
title: Python in PSX with Curly Braces 🚫
---

!!! warning "In Progress"

This feature is planned, but not yet developed.

See [this issue](https://github.com/reactive-python/reactpy/issues/918) for more details.

## Overview

<p class="intro" markdown>
Expand All @@ -17,6 +23,7 @@ JSX lets you write HTML-like markup inside a JavaScript file, keeping rendering
- How to call a JavaScript function inside JSX with curly braces
- How to use a JavaScript object inside JSX with curly braces

<!--
## Passing strings with quotes

When you want to pass a string attribute to JSX, you put it in single or double quotes:
Expand Down Expand Up @@ -588,4 +595,4 @@ Variables and functions can help you keep the markup simple!

</Solution>

</Challenges>
</Challenges> -->
13 changes: 6 additions & 7 deletions docs/src/learn/react-developer-tools.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,12 @@
title: React Developer Tools 🚫
---

!!! warning "In Progress"

This feature is planned, but not yet developed.

See [this issue](https://github.com/reactive-python/reactpy/issues/1072) for more details.

## Overview

<p class="intro" markdown>
Expand All @@ -14,13 +20,6 @@ Use React Developer Tools to inspect React [components](../learn/your-first-comp

- How to install ReactPy Developer Tools


!!! warning "In Progress"

This feature is planned, but not yet developed.

See [this issue](https://github.com/reactive-python/reactpy/issues/1072) for more details.

<!--
## Browser extension

Expand Down
54 changes: 29 additions & 25 deletions docs/src/learn/writing-markup-with-psx.md
Original file line number Diff line number Diff line change
@@ -1,42 +1,46 @@
---
title: Writing Markup with PSX 🚧
title: Writing Markup with PSX 🚫
---

!!! warning "In Progress"

This feature is planned, but not yet developed.

See [this issue](https://github.com/reactive-python/reactpy/issues/918) for more details.

## Overview

<p class="intro" markdown>

_JSX_ is a syntax extension for JavaScript that lets you write HTML-like markup inside a JavaScript file. Although there are other ways to write components, most React developers prefer the conciseness of JSX, and most codebases use it.
_PSX_ is a syntax extension for JavaScript that lets you write HTML-like markup inside a JavaScript file. Although there are other ways to write components, most React developers prefer the conciseness of PSX, and most codebases use it.

</p>

!!! summary "You Will Learn"

- Why React mixes markup with rendering logic
- How JSX is different from HTML
- How to display information with JSX
- How PSX is different from HTML
- How to display information with PSX

## JSX: Putting markup into JavaScript
## PSX: Putting markup into Python

The Web has been built on HTML, CSS, and JavaScript. For many years, web developers kept content in HTML, design in CSS, and logic in JavaScript—often in separate files! Content was marked up inside HTML while the page's logic lived separately in JavaScript:

<!-- TODO: Diagram -->

But as the Web became more interactive, logic increasingly determined content. JavaScript was in charge of the HTML! This is why **in React, rendering logic and markup live together in the same place—components.**
But as the Web became more interactive, logic increasingly determined content. Scripting languages are now in charge of the HTML! This is why **in React, rendering logic and markup live together in the same place—components.**

<!-- TODO: Diagram -->

Keeping a button's rendering logic and markup together ensures that they stay in sync with each other on every edit. Conversely, details that are unrelated, such as the button's markup and a sidebar's markup, are isolated from each other, making it safer to change either of them on their own.

Each React component is a JavaScript function that may contain some markup that React renders into the browser. React components use a syntax extension called JSX to represent that markup. JSX looks a lot like HTML, but it is a bit stricter and can display dynamic information. The best way to understand this is to convert some HTML markup to JSX markup.
Each React component is a JavaScript function that may contain some markup that React renders into the browser. React components use a syntax extension called PSX to represent that markup. PSX looks a lot like HTML, but it is a bit stricter and can display dynamic information. The best way to understand this is to convert some HTML markup to PSX markup.

<Note>

JSX and React are two separate things. They're often used together, but you _can_ [use them independently](https://reactjs.org/blog/2020/09/22/introducing-the-new-jsx-transform.html#whats-a-jsx-transform) of each other. JSX is a syntax extension, while React is a JavaScript library.
!!! note

</Note>
PSX and ReactPy are two separate things. They're often used together, but you _can_ use them independently of each other. PSX is a syntax extension, while ReactPy is a Python library.

## Converting HTML to JSX
<!-- ## Converting HTML to PSX

Suppose that you have some (perfectly valid) HTML:

Expand Down Expand Up @@ -87,15 +91,15 @@ img {
}
```

This is because JSX is stricter and has a few more rules than HTML! If you read the error messages above, they'll guide you to fix the markup, or you can follow the guide below.
This is because PSX is stricter and has a few more rules than HTML! If you read the error messages above, they'll guide you to fix the markup, or you can follow the guide below.

<Note>

Most of the time, React's on-screen error messages will help you find where the problem is. Give them a read if you get stuck!

</Note>

## The Rules of JSX
## The Rules of PSX

### 1. Return a single root element

Expand Down Expand Up @@ -137,15 +141,15 @@ This empty tag is called a _[Fragment.](/reference/react/Fragment)_ Fragments le

<DeepDive>

#### Why do multiple JSX tags need to be wrapped?
#### Why do multiple PSX tags need to be wrapped?

JSX looks like HTML, but under the hood it is transformed into plain JavaScript objects. You can't return two objects from a function without wrapping them into an array. This explains why you also can't return two JSX tags without wrapping them into another tag or a Fragment.
PSX looks like HTML, but under the hood it is transformed into plain JavaScript objects. You can't return two objects from a function without wrapping them into an array. This explains why you also can't return two PSX tags without wrapping them into another tag or a Fragment.

</DeepDive>

### 2. Close all the tags

JSX requires tags to be explicitly closed: self-closing tags like `<img>` must become `<img />`, and wrapping tags like `<li>oranges` must be written as `<li>oranges</li>`.
PSX requires tags to be explicitly closed: self-closing tags like `<img>` must become `<img />`, and wrapping tags like `<li>oranges` must be written as `<li>oranges</li>`.

This is how Hedy Lamarr's image and list items look closed:

Expand All @@ -166,7 +170,7 @@ This is how Hedy Lamarr's image and list items look closed:

### 3. camelCase <s>all</s> most of the things!

JSX turns into JavaScript and attributes written in JSX become keys of JavaScript objects. In your own components, you will often want to read those attributes into variables. But JavaScript has limitations on variable names. For example, their names can't contain dashes or be reserved words like `class`.
PSX turns into JavaScript and attributes written in PSX become keys of JavaScript objects. In your own components, you will often want to read those attributes into variables. But JavaScript has limitations on variable names. For example, their names can't contain dashes or be reserved words like `class`.

This is why, in React, many HTML and SVG attributes are written in camelCase. For example, instead of `stroke-width` you use `strokeWidth`. Since `class` is a reserved word, in React you write `className` instead, named after the [corresponding DOM property](https://developer.mozilla.org/en-US/docs/Web/API/Element/className):

Expand All @@ -186,9 +190,9 @@ For historical reasons, [`aria-*`](https://developer.mozilla.org/docs/Web/Access

</Pitfall>

### Pro-tip: Use a JSX Converter
### Pro-tip: Use a PSX Converter

Converting all these attributes in existing markup can be tedious! We recommend using a [converter](https://transform.tools/html-to-jsx) to translate your existing HTML and SVG to JSX. Converters are very useful in practice, but it's still worth understanding what is going on so that you can comfortably write JSX on your own.
Converting all these attributes in existing markup can be tedious! We recommend using a [converter](https://transform.tools/html-to-psx) to translate your existing HTML and SVG to PSX. Converters are very useful in practice, but it's still worth understanding what is going on so that you can comfortably write PSX on your own.

Here is your final result:

Expand Down Expand Up @@ -220,19 +224,19 @@ img {

<Recap>

Now you know why JSX exists and how to use it in components:
Now you know why PSX exists and how to use it in components:

- React components group rendering logic together with markup because they are related.
- JSX is similar to HTML, with a few differences. You can use a [converter](https://transform.tools/html-to-jsx) if you need to.
- PSX is similar to HTML, with a few differences. You can use a [converter](https://transform.tools/html-to-psx) if you need to.
- Error messages will often point you in the right direction to fixing your markup.

</Recap>

<Challenges>

#### Convert some HTML to JSX
#### Convert some HTML to PSX

This HTML was pasted into a component, but it's not valid JSX. Fix it:
This HTML was pasted into a component, but it's not valid PSX. Fix it:

```js
export default function Bio() {
Expand Down Expand Up @@ -323,4 +327,4 @@ export default function Bio() {

</Solution>

</Challenges>
</Challenges> -->