Skip to content

Commit 21a94c0

Browse files
rmorshearmorshea
committed
docs reorganization
1 parent ac90cbb commit 21a94c0

34 files changed

+428
-327
lines changed

‎docs/source/_exts/autogen_api_docs.py

+4-4
Original file line numberDiff line numberDiff line change
@@ -9,11 +9,11 @@
99
HERE = Path(__file__).parent
1010
PACKAGE_SRC = HERE.parent.parent.parent / "src"
1111

12-
REFERENCES_DIR = HERE.parent / "references"
13-
REFERENCES_DIR.mkdir(exist_ok=True)
12+
AUTOGEN_DIR = HERE.parent / "autogen"
13+
AUTOGEN_DIR.mkdir(exist_ok=True)
1414

15-
PUBLIC_API_REFERENCE_FILE = REFERENCES_DIR / "user-apis.rst"
16-
PRIVATE_API_REFERENCE_FILE = REFERENCES_DIR / "developer-apis.rst"
15+
PUBLIC_API_REFERENCE_FILE = AUTOGEN_DIR / "user-apis.rst"
16+
PRIVATE_API_REFERENCE_FILE = AUTOGEN_DIR / "developer-apis.rst"
1717

1818

1919
PUBLIC_TITLE = "User API\n=============\n"

‎docs/source/_static/vdom-json-schema.json

+122
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,122 @@
1+
{
2+
"$ref": "#/definitions/element",
3+
"$schema": "http://json-schema.org/draft-07/schema",
4+
"definitions": {
5+
"element": {
6+
"dependentSchemas": {
7+
"error": {
8+
"properties": {
9+
"tagName": {
10+
"maxLength": 0
11+
}
12+
}
13+
}
14+
},
15+
"properties": {
16+
"attributes": {
17+
"type": "object"
18+
},
19+
"children": {
20+
"$ref": "#/definitions/elementChildren"
21+
},
22+
"error": {
23+
"type": "string"
24+
},
25+
"eventHandlers": {
26+
"$ref": "#/definitions/elementEventHandlers"
27+
},
28+
"importSource": {
29+
"$ref": "#/definitions/importSource"
30+
},
31+
"key": {
32+
"type": "string"
33+
},
34+
"tagName": {
35+
"type": "string"
36+
}
37+
},
38+
"required": [
39+
"tagName"
40+
],
41+
"type": "object"
42+
},
43+
"elementChildren": {
44+
"items": {
45+
"$ref": "#/definitions/elementOrString"
46+
},
47+
"type": "array"
48+
},
49+
"elementEventHandlers": {
50+
"patternProperties": {
51+
".*": {
52+
"$ref": "#/definitions/eventHander"
53+
}
54+
},
55+
"type": "object"
56+
},
57+
"elementOrString": {
58+
"if": {
59+
"type": "object"
60+
},
61+
"then": {
62+
"$ref": "#/definitions/element"
63+
},
64+
"type": [
65+
"object",
66+
"string"
67+
]
68+
},
69+
"eventHander": {
70+
"properties": {
71+
"preventDefault": {
72+
"type": "boolean"
73+
},
74+
"stopPropagation": {
75+
"type": "boolean"
76+
},
77+
"target": {
78+
"type": "string"
79+
}
80+
},
81+
"required": [
82+
"target"
83+
],
84+
"type": "object"
85+
},
86+
"importSource": {
87+
"properties": {
88+
"fallback": {
89+
"if": {
90+
"not": {
91+
"type": "null"
92+
}
93+
},
94+
"then": {
95+
"$ref": "#/definitions/elementOrString"
96+
},
97+
"type": [
98+
"object",
99+
"string",
100+
"null"
101+
]
102+
},
103+
"source": {
104+
"type": "string"
105+
},
106+
"sourceType": {
107+
"enum": [
108+
"URL",
109+
"NAME"
110+
]
111+
},
112+
"unmountBeforeUpdate": {
113+
"type": "boolean"
114+
}
115+
},
116+
"required": [
117+
"source"
118+
],
119+
"type": "object"
120+
}
121+
}
122+
}

‎docs/source/references/core-abstractions.rst renamed to ‎docs/source/advanced-topics/core-abstractions.rst

+5-5
Original file line numberDiff line numberDiff line change
@@ -26,11 +26,11 @@ accepted a list of strings and turned it into a series of paragraph elements:
2626
Stateful Components
2727
-------------------
2828

29-
A Stateful Component is one which uses a :ref:`Life Cycle Hooks`. These life cycle hooks
30-
allow you to add state to otherwise stateless functions. To create a stateful component
31-
you'll need to apply the :func:`~idom.core.component.component` decorator to a coroutine_
32-
whose body contains a hook usage. We'll demonstrate that with a simple
33-
:ref:`click counter`:
29+
A Stateful Component is one which uses a :ref:`Life Cycle Hooks <Introduction to
30+
Hooks>`. These life cycle hooks allow you to add state to otherwise stateless functions.
31+
To create a stateful component you'll need to apply the
32+
:func:`~idom.core.component.component` decorator to a coroutine_ whose body contains a
33+
hook usage. We'll demonstrate that with a simple :ref:`click counter`:
3434

3535
.. testcode::
3636

‎docs/source/javascript-components.rst renamed to ‎docs/source/advanced-topics/javascript-components.rst

+2-2
Original file line numberDiff line numberDiff line change
@@ -43,8 +43,8 @@ be using the ubiquitous React-based UI framework `Material UI`_.
4343

4444
So now that we can display a Material UI Button we probably want to make it do
4545
something. Thankfully there's nothing new to learn here, you can pass event handlers to
46-
the button just as you did when :ref:`getting started`. Thus, all we need to do is add
47-
an ``onClick`` handler to the component:
46+
the button just as you did when :ref:`getting started <handling events>`. Thus, all we
47+
need to do is add an ``onClick`` handler to the component:
4848

4949
.. example:: material_ui_button_on_click
5050

‎docs/source/references/developer-apis.rst renamed to ‎docs/source/autogen/developer-apis.rst

File renamed without changes.

‎docs/source/references/user-apis.rst renamed to ‎docs/source/autogen/user-apis.rst

File renamed without changes.

‎docs/source/examples/simple_dashboard.py

+1-1
Original file line numberDiff line numberDiff line change
@@ -84,7 +84,7 @@ def update_value(value):
8484

8585
return idom.html.fieldset(
8686
{"class": "number-input-container"},
87-
[idom.html.legend({"style": {"font-size": "medium"}}, label)],
87+
idom.html.legend({"style": {"font-size": "medium"}}, label),
8888
Input(update_value, "number", value, attributes=attrs, cast=float),
8989
Input(update_value, "range", value, attributes=attrs, cast=float),
9090
)

‎docs/source/getting-started/component-basics.rst

+4
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
Basics of Components (WIP)
2+
==========================
3+
4+
Under construction :)

‎docs/source/getting-started/conditional-rendering.rst

+4
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
Conditional Rendering (WIP)
2+
===========================
3+
4+
Under construction :)

‎docs/source/tutorials/handling-events.rst renamed to ‎docs/source/getting-started/handling-events.rst

+4-4
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,10 @@
11
Handling Events
22
===============
33

4-
When :ref:`Getting Started`, we saw how IDOM makes it possible to write server-side code
5-
that defines basic views and can react to client-side events. The simplest way to listen
6-
and respond to events is by assigning a callable object to a :ref:`VDOM`
7-
an attribute where event signals are sent. This is relatively similar to
4+
When :ref:`Getting Started <Hello World>`, we saw how IDOM makes it possible to write
5+
server-side code that defines basic views and can react to client-side events. The
6+
simplest way to listen and respond to events is by assigning a callable object to a
7+
:ref:`VDOM` an attribute where event signals are sent. This is relatively similar to
88
`handling events in React`_:
99

1010
.. _handling events in React: https://reactjs.org/docs/handling-events.html

‎docs/source/getting-started/hello-world.rst

+4
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
Hello World (WIP)
2+
=================
3+
4+
Under construction :)

‎docs/source/getting-started/installation.rst

+46
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
Installation
2+
============
3+
4+
You can install IDOM with ``pip``:
5+
6+
.. code-block:: bash
7+
8+
pip install idom[stable]
9+
10+
.. note::
11+
12+
Some shells may require you to inclose the install target in quotes
13+
(e.g. ``"idom[stable]"``)
14+
15+
This includes a default implementation for its :ref:`Layout Server`. You can switch to a
16+
different one by replacing ``stable`` with one of the following other options:
17+
18+
- ``fastapi`` - https://fastapi.tiangolo.com
19+
- ``flask`` - https://palletsprojects.com/p/flask/
20+
- ``sanic`` - https://sanicframework.org
21+
- ``tornado`` - https://www.tornadoweb.org/en/stable/
22+
23+
If you need to you can install more than one option by separating them with commas:
24+
25+
.. code-block:: bash
26+
27+
pip install idom[fastapi,flask,sanic,tornado,testing]
28+
29+
.. note::
30+
31+
If you want to integrate IDOM with `Django <https://www.djangoproject.com/>`__
32+
you'll need to use `django-idom <https://github.com/idom-team/django-idom>`__
33+
instead.
34+
35+
Install Test Tooling
36+
--------------------
37+
38+
IDOM also provides some useful tools to ensure your applications run correctly. You
39+
can install these with ``pip`` similarly to the server implementations above:
40+
41+
.. code-block:: bash
42+
43+
pip install idom[testing]
44+
45+
This will install ``selenium`` which is useful when unit testing along with
46+
``flake8-idom-hooks`` which is used to enforce the :ref:`Rules of Hooks`.

‎docs/source/getting-started/lists-and-keys.rst

+4
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
Lists and Keys (WIP)
2+
====================
3+
4+
Under construction :)

‎docs/source/getting-started/rendering-elements.rst

+4
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
Rendering Elements (WIP)
2+
========================
3+
4+
Under construction :)

‎docs/source/getting-started/state-management.rst

+4
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
State Management (WIP)
2+
======================
3+
4+
Under construction :)

‎docs/source/guides/basic-dashboard.rst

-6
This file was deleted.

‎docs/source/guides/making-a-game.rst

-8
This file was deleted.

‎docs/source/guides/matplotlib-plot.rst

-6
This file was deleted.

0 commit comments

Comments
 (0)