diff --git a/docs/source/developing-idom/changelog.rst b/docs/source/about/changelog.rst similarity index 92% rename from docs/source/developing-idom/changelog.rst rename to docs/source/about/changelog.rst index ab678f088..6df2b732a 100644 --- a/docs/source/developing-idom/changelog.rst +++ b/docs/source/about/changelog.rst @@ -1,11 +1,41 @@ Changelog ========= -The IDOM team manages their short and long term plans with `GitHub Projects -`__. If you have questions about what the -team are working on, or have feedback on how issues should be prioritized, feel free to -:discussion-type:`open up a discussion `. +.. note:: + The IDOM team manages their short and long term plans with `GitHub Projects + `__. If you have questions about what + the team are working on, or have feedback on how issues should be prioritized, feel + free to :discussion-type:`open up a discussion `. + +All notable changes to this project will be recorded in this document. The style of +which is based on `Keep a Changelog `__. The versioning +scheme for the project adheres to `Semantic Versioning `__. + + +Unreleased +---------- + +While this release doesn't warrant a minor version bump, the last release should have +been. Thus, to make up for that, this release will be a minor bump. It includes misc +bug fixes, and several feature adds, the most important of which is the addition of the +``use_context`` hook. + +Added: + +- Support for keys in HTML fragments - :issue:`682` + +**Merged Pull Requests** + +- reset schedule_render_later flag after triggering - :pull:`688` +- support keys in HTML fragments - :pull:`683` +- Add Use Context Hook - :pull:`585` + +---- + +Releases below do not use the "Keep a Changelog" style guidelines. + +---- 0.36.3 ------ @@ -92,7 +122,7 @@ for elements at the root did not trigger unmounts. ------ As part of :pull:`614`, elements which changed type were not deeply unmounted. This -behavior is probably undesireable though since the state for children of the element +behavior is probably undesirable though since the state for children of the element in question would persist (probably unexpectedly). **Pull Requests** @@ -136,7 +166,7 @@ this marker file. The highlight of this release is that the default :ref:`"key" ` of all elements will be their index amongst their neighbors. Previously this behavior could be engaged by setting ``IDOM_FEATURE_INDEX_AS_DEFAULT_KEY=1`` when -running IDOM. In this release though, you will need to explicitely turn off this feature +running IDOM. In this release though, you will need to explicitly turn off this feature (i.e. ``=0``) to return to the old behavior. With this change, some may notice additional error logs which warn that: @@ -200,7 +230,7 @@ event dictionary. As part of this change we also add ``event["currentTarget"]`` 0.33.3 ------ -Contains a small number of bug fixes and improvements. The most signicifact change is +Contains a small number of bug fixes and improvements. The most significant change is the addition of a warning stating that `IDOM_FEATURE_INDEX_AS_DEFAULT_KEY=1` will become the default in a future release. Beyond that, a lesser improvement makes it possible to use the default export from a Javascript module when calling `module_from_template` by @@ -277,7 +307,7 @@ yet. - move VdomDict and VdomJson to proto - :pull:`492` - only send error info in debug mode - :pull:`491` -- correcly apply client-side JSON patch - :pull:`490` +- correctly apply client-side JSON patch - :pull:`490` - add script to set version of all packages in IDOM - :pull:`483` - Pass import source to bind - :pull:`482` - Do not mutate client-side model - :pull:`481` @@ -339,12 +369,12 @@ The latter behavior is the most egregious design issue since there's absolutely indication that the component instance can be swapped out (not even a comment). The new refactor no longer binds component or layout instances to a ``LifeCycleHook``. -Instead, the hook simply receives an unparametrized callback that can be triggered to +Instead, the hook simply receives an un-parametrized callback that can be triggered to schedule a render. While some error logs lose clarity (since we can't say what component caused them). This change precludes a need for the layout to ever mutate the hook. -To accomodate this change, the internal representation of the layout's state had to -change. Previsouly, a class-based approach was take, where methods of the state-holding +To accommodate this change, the internal representation of the layout's state had to +change. Previously, a class-based approach was take, where methods of the state-holding classes were meant to handle all use cases. Now we rely much more heavily on very simple (and mostly static) data structures that have purpose built constructor functions that much more narrowly address each use case. @@ -497,7 +527,7 @@ and breaking changes, the most significant of which are: - refactor flask - :commit:`94681b6` - refactor tornado + misc fixes to sanic/fastapi - :commit:`16c9209` - refactor fastapi using server protocol - :commit:`0cc03ba` -- recactor sanic server - :commit:`43d4b4f` +- refactor sanic server - :commit:`43d4b4f` - use server protocol instead of inheritance - :commit:`abe0fde` - support currentTime attr of audio/video elements - :commit:`975b54a` - pass children as props to mount() - :commit:`9494bc0` @@ -554,7 +584,7 @@ several bugs that had cropped up related to improper usage of ``anyio``. **Highlighted Commits:** -- improve docs + simplify multiview - :commit:`4129b60` +- improve docs + simplify multi-view - :commit:`4129b60` - require anyio>=3.0 - :commit:`24aed28` - refactor dispatchers - :commit:`ce8e060` diff --git a/docs/source/developing-idom/contributor-guide.rst b/docs/source/about/contributor-guide.rst similarity index 70% rename from docs/source/developing-idom/contributor-guide.rst rename to docs/source/about/contributor-guide.rst index 8937f12e3..56de0d747 100644 --- a/docs/source/developing-idom/contributor-guide.rst +++ b/docs/source/about/contributor-guide.rst @@ -1,17 +1,42 @@ Contributor Guide ================= +.. note:: + + The + `Code of Conduct `__ + applies in all community spaces. If you are not familiar with our Code of Conduct + policy, take a minute to read it before making your first contribution. + +The IDOM team welcomes contributions and contributors of all kinds - whether they come +as code changes, participation in the discussions, opening issues and pointing out bugs, +or simply sharing your work with your colleagues and friends. We're excited to see how +you can help move this project and community forward! + + +.. _everyone can contribute: + +Everyone Can Contribute! +------------------------ + +Trust us, there's so many ways to support the project. We're always looking for people +who can: + +- Improve our documentation +- Teach and tell others about IDOM +- Share ideas for new features +- Report bugs +- Participate in general discussions + +Still aren't sure what you have to offer? Just :discussion-type:`ask us ` and +we'll help you make your first contribution. + + .. note:: If you have any questions during set up or development post on our :discussion-type:`discussion board ` and we'll answer them. -This project uses the `GitHub Flow`_ (more detail :ref:`below `) -for collaboration and consists primarily of Python code and Javascript code. A -:ref:`variety of tools ` are used to aid in its development. -Any code contributed to IDOM is validated by a :ref:`series of tests ` to ensure its quality and correctness. - Making a Pull Request --------------------- @@ -41,6 +66,47 @@ about how to get started. To make a change to IDOM you'll do the following: :ref:`equality checks ` and, with any luck, accept your request. At that point your contribution will be merged into the main codebase! +Create a Changelog Entry +........................ + +As part of your pull request, you'll want to edit the :ref:`Changelog` by adding an +entry describing what you've changed or improved. You should write an entry in the style +of `Keep a Changelog `__ that falls under one of the +following categories, and add it to the :ref:`Unreleased` section of the changelog: + +- **Added** - for new features. +- **Changed** - for changes in existing functionality. +- **Deprecated** - for soon-to-be removed features. +- **Removed** - for now removed features. +- **Fixed** - for any bug fixes. +- **Documented** - for improvements to this documentation. +- **Security** - in case of vulnerabilities. + +If one of the sections doesn't exist, add it. If it does already, add a bullet point +under the relevant section. Here's a short example of what an unreleased changelog entry +might look like: + +.. code-block:: rst + + Unreleased + ---------- + + **Added** + + - A really cool new feature - :pull:`123` + + **Changed** + + - The behavior of some existing feature - :pull:`456` + + **Fixed** + + - Some really bad bug - :issue:`789` + +.. note:: + + ``:issue:`` and ``:pull:`` refer to issue and pull request ticket numbers. + Development Environment ----------------------- @@ -104,7 +170,7 @@ However you may also ``cd`` to the ``src/client`` directory which contains a Running The Tests ----------------- -The test suite for IDOM uses Nox_ and NPM_ in order to validate: +The test suite for IDOM is executed with Nox_. The suite covers: 1. Server-side Python code with PyTest_ @@ -112,11 +178,7 @@ The test suite for IDOM uses Nox_ and NPM_ in order to validate: 3. Client-side Javascript code with UVU_ - -Running Python Tests -.................... - -To run the full suite of Python tests you'll need to install: +To run the full suite of tests you'll need to install: - `Google Chrome`_ @@ -126,8 +188,7 @@ To run the full suite of Python tests you'll need to install: Be sure the version of `Google Chrome`_ and ChromeDriver_ you install are compatible. -Once you've installed the aforementioned browser and web driver you should be able to -run: +Once you've installed the aforementioned browser and web driver you'll be able to run: .. code-block:: bash @@ -139,27 +200,6 @@ If you prefer to run the tests using a headless browser: nox -s test -- --headless -You can pass other options to pytest in a similar manner: - -.. code-block:: bash - - nox -s test -- arg --flag --key=value - - -Running Javascript Tests -........................ - -If you've already run ``npm install`` inside the ``src/idom/client/app`` directory, you -can execute the suite of workspace tests under ``packages/*`` with: - -.. code-block:: - - npm test - -As a final check, you might want to run ``npm run build``. This command is run in the -top-level ``setup.py`` installation script for the Python package, so if this command -fails, the installation of the Python package with ``pip`` will too. - Code Quality Checks ------------------- @@ -175,11 +215,12 @@ The following are currently being used: - Black_ - an opinionated code formatter - Flake8_ - a style guide enforcement tool - ISort_ - a utility for alphabetically sorting imports -- Prettier_ - a tool for autimatically formatting Javascript code +- Prettier_ - a tool for automatically formatting various file types -The most strict measure of quality enforced on the codebase is 100% coverage. This means -that every line of coded added to IDOM requires a test case that exercises it. This -doesn't prevent all bugs, but it should ensure that we catch the most common ones. +The most strict measure of quality enforced on the codebase is 100% test coverage in +Python files. This means that every line of coded added to IDOM requires a test case +that exercises it. This doesn't prevent all bugs, but it should ensure that we catch the +most common ones. If you need help understanding why code you've submitted does not pass these checks, then be sure to ask, either in the :discussion-type:`Community Forum ` or in @@ -196,7 +237,7 @@ your :ref:`Pull Request `. Building The Documentation -------------------------- -To build and display the documentation simply run: +To build and display the documentation locally run: .. code-block:: bash @@ -215,13 +256,13 @@ To run some of the examples in the documentation as if they were tests run: nox -s test_docs Building the documentation as it's deployed in production requires Docker_. Once you've -installed, you can run: +installed Docker, you can run: .. code-block:: bash nox -s docs_in_docker -You should then navigate to to see the documentation. +Where you can then navigate to http://localhost:5000.. Release Process @@ -249,58 +290,7 @@ To update the version for all core Javascript and Python packages in IDOM run: .. note:: - The new version must adhere to `SemVer `__. Once IDOM - becomes stable we will shift to using `CalVer `__. - - -Create Changelog Entry -...................... - -Immediately after updating the version you'll need to create a changelog entry for the -release. This should **always** include a human authored summary of the changes it -includes. For example, new or deprecated features, performance improvements, and bug -fixes (whatever is relevant). To help with this, there are some useful tools for -gathering the Pull Requests and Issues that have been merged and resolved since the last -release. While reviewing these items can help in writing a human authored release -summary, you **must not** resort to a bullet list of Pull Request and Issue -descriptions. Putting these two together, the format of a changelog entry should look a -bit like this: - -.. code-block:: text - - X.Y.Z - ----- - - The release summary... - - **Closed Issues** - - - Some issue - :issue:`123` - - Another issue - :issue:`456` - - **Pull Requests** - - - Some pull request - :pull:`123` - - Another pull request - :pull:`456` - - **Deprecated Features** - - - Description one - - Description two - -To create the list of pull requests and closed issues you can copy the output of the -following commands using the ```` of your choosing (``rst``, ``md``, ``text``): - -.. note:: - - You should currate the list - not everything needs to be included. - -.. code-block:: bash - - nox -s changes_since_release -- - -Once the version has been updated and the changelog entry completed, you should commit -the changes. + The new version must adhere to `SemVer `__. Creating The Release @@ -321,12 +311,12 @@ To create the release tag you can run the following command: nox -s tag -- push -Last, you must create a -`"Release" `__ +Last, you must create a `"Release" +`__ in GitHub. Because we pushed a tag using the command above, there should already be a -saved draft which needs a title and desription. The title should simply be the version -(same as the tag), and the description should, at minimum, be a markdown version of the -already authored :ref:`Changelog summary `. +saved draft which needs a title and description. The title should simply be the version +(same as the tag), and the description should simply use GitHub's "Auto-generated +release notes". Other Core Repositories diff --git a/docs/source/credits-and-licenses.rst b/docs/source/about/credits-and-licenses.rst similarity index 93% rename from docs/source/credits-and-licenses.rst rename to docs/source/about/credits-and-licenses.rst index 5aef11a59..4bc1544f2 100644 --- a/docs/source/credits-and-licenses.rst +++ b/docs/source/about/credits-and-licenses.rst @@ -12,5 +12,5 @@ copy language or examples where IDOM's behavior mirrors that of React's. Source Code License ------------------- -.. literalinclude:: ../../LICENSE +.. literalinclude:: ../../../LICENSE :language: text diff --git a/docs/source/developing-idom/index.rst b/docs/source/developing-idom/index.rst deleted file mode 100644 index e9a881cf2..000000000 --- a/docs/source/developing-idom/index.rst +++ /dev/null @@ -1,65 +0,0 @@ -Developing IDOM -=============== - -.. toctree:: - :hidden: - - contributor-guide - changelog - -.. note:: - - The - `Code of Conduct `__ - applies in all community spaces. If you are not familiar with our Code of Conduct - policy, take a minute to read it before making your first contribution. - -The IDOM team welcomes contributions and contributors of all kinds - whether they come -as code changes, participation in the discussions, opening issues and pointing out bugs, -or simply sharing your work with your colleagues and friends. We're excited to see how -you can help move this project and community forward! - - -.. grid:: 1 2 2 2 - :gutter: 1 - - .. grid-item-card:: :octicon:`people` Discussion Forum - :link: https://github.com/idom-team/idom/discussions - - Ask questions, share ideas, or show projects - - .. grid-item-card:: :octicon:`info` Contributor Guide - :link: contributor-guide - :link-type: doc - - Learn how to make changes to IDOM and submit them back to the project - - .. grid-item-card:: :octicon:`git-pull-request` Changelog - :link: changelog - :link-type: doc - - Discover the features and fixes included in each release - - .. grid-item-card:: :octicon:`milestone` Roadmap - :link: https://github.com/orgs/idom-team/projects/1 - :link-type: url - - See the long term goals of the IDOM team - - -.. _everyone can contribute: - -Everyone Can Contribute! ------------------------- - -Trust us, there's so many ways to support the project. We're always looking for people -who can: - -- Improve our documentation -- Teach and tell others about IDOM -- Share ideas for new features -- Report bugs -- Participate in general discussions - -Still aren't sure what you have to offer? Just :discussion-type:`ask us ` and -we'll help you make your first contribution. diff --git a/docs/source/adding-interactivity/components-with-state/_examples/adding_state_variable/app.py b/docs/source/guides/adding-interactivity/components-with-state/_examples/adding_state_variable/app.py similarity index 100% rename from docs/source/adding-interactivity/components-with-state/_examples/adding_state_variable/app.py rename to docs/source/guides/adding-interactivity/components-with-state/_examples/adding_state_variable/app.py diff --git a/docs/source/adding-interactivity/components-with-state/_examples/adding_state_variable/data.json b/docs/source/guides/adding-interactivity/components-with-state/_examples/adding_state_variable/data.json similarity index 100% rename from docs/source/adding-interactivity/components-with-state/_examples/adding_state_variable/data.json rename to docs/source/guides/adding-interactivity/components-with-state/_examples/adding_state_variable/data.json diff --git a/docs/source/adding-interactivity/components-with-state/_examples/isolated_state/app.py b/docs/source/guides/adding-interactivity/components-with-state/_examples/isolated_state/app.py similarity index 100% rename from docs/source/adding-interactivity/components-with-state/_examples/isolated_state/app.py rename to docs/source/guides/adding-interactivity/components-with-state/_examples/isolated_state/app.py diff --git a/docs/source/adding-interactivity/components-with-state/_examples/isolated_state/data.json b/docs/source/guides/adding-interactivity/components-with-state/_examples/isolated_state/data.json similarity index 100% rename from docs/source/adding-interactivity/components-with-state/_examples/isolated_state/data.json rename to docs/source/guides/adding-interactivity/components-with-state/_examples/isolated_state/data.json diff --git a/docs/source/adding-interactivity/components-with-state/_examples/multiple_state_variables/app.py b/docs/source/guides/adding-interactivity/components-with-state/_examples/multiple_state_variables/app.py similarity index 100% rename from docs/source/adding-interactivity/components-with-state/_examples/multiple_state_variables/app.py rename to docs/source/guides/adding-interactivity/components-with-state/_examples/multiple_state_variables/app.py diff --git a/docs/source/adding-interactivity/components-with-state/_examples/multiple_state_variables/data.json b/docs/source/guides/adding-interactivity/components-with-state/_examples/multiple_state_variables/data.json similarity index 100% rename from docs/source/adding-interactivity/components-with-state/_examples/multiple_state_variables/data.json rename to docs/source/guides/adding-interactivity/components-with-state/_examples/multiple_state_variables/data.json diff --git a/docs/source/adding-interactivity/components-with-state/_examples/when_variables_arent_enough/app.py b/docs/source/guides/adding-interactivity/components-with-state/_examples/when_variables_are_not_enough/app.py similarity index 100% rename from docs/source/adding-interactivity/components-with-state/_examples/when_variables_arent_enough/app.py rename to docs/source/guides/adding-interactivity/components-with-state/_examples/when_variables_are_not_enough/app.py diff --git a/docs/source/adding-interactivity/components-with-state/_examples/when_variables_arent_enough/data.json b/docs/source/guides/adding-interactivity/components-with-state/_examples/when_variables_are_not_enough/data.json similarity index 100% rename from docs/source/adding-interactivity/components-with-state/_examples/when_variables_arent_enough/data.json rename to docs/source/guides/adding-interactivity/components-with-state/_examples/when_variables_are_not_enough/data.json diff --git a/docs/source/adding-interactivity/components-with-state/index.rst b/docs/source/guides/adding-interactivity/components-with-state/index.rst similarity index 97% rename from docs/source/adding-interactivity/components-with-state/index.rst rename to docs/source/guides/adding-interactivity/components-with-state/index.rst index 93928e05d..5c9161de2 100644 --- a/docs/source/adding-interactivity/components-with-state/index.rst +++ b/docs/source/guides/adding-interactivity/components-with-state/index.rst @@ -16,7 +16,7 @@ Below is a gallery of images about sculpture. Clicking the "Next" button should increment the ``index`` and, as a result, change what image is displayed. However, this does not work: -.. idom:: _examples/when_variables_arent_enough +.. idom:: _examples/when_variables_are_not_enough .. note:: @@ -42,7 +42,7 @@ that still wouldn't fix the underlying problems: To address these problems, IDOM provides the :func:`~idom.core.hooks.use_state` "hook" which provides: -1. A **state variable** whose data is retained aross renders. +1. A **state variable** whose data is retained across renders. 2. A **state setter** function that can be used to update that variable and trigger a render. @@ -130,7 +130,7 @@ Thus, in this example: of the component. The convention is that, if you name your state variable ``thing``, your state setter -should be named ``set_thing``. While you could name them anything you want, adhereing to +should be named ``set_thing``. While you could name them anything you want, adhering to the convention makes things easier to understand across projects. ---- @@ -308,7 +308,7 @@ displayed and ``show_more`` is solely concerned with whether the description for sculpture is shown. Put other way ``index`` is concerned with *what* information is displayed while ``show_more`` is concerned with *how* it is displayed. Conversely though, if you have a form with many fields, it probably makes sense to have a single -objec that holds the data for all the fields rather than an object per-field. +object that holds the data for all the fields rather than an object per-field. .. note:: @@ -340,7 +340,7 @@ it. The parent component canโ€™t change it. This lets you add state to any compo remove it without impacting the rest of the components. .. card:: - :link: /managing-state/sharing-component-state/index + :link: /guides/managing-state/sharing-component-state/index :link-type: doc :octicon:`book` Read More diff --git a/docs/source/adding-interactivity/dangers-of-mutability/_examples/dict_remove.py b/docs/source/guides/adding-interactivity/dangers-of-mutability/_examples/dict_remove.py similarity index 100% rename from docs/source/adding-interactivity/dangers-of-mutability/_examples/dict_remove.py rename to docs/source/guides/adding-interactivity/dangers-of-mutability/_examples/dict_remove.py diff --git a/docs/source/adding-interactivity/dangers-of-mutability/_examples/dict_update.py b/docs/source/guides/adding-interactivity/dangers-of-mutability/_examples/dict_update.py similarity index 100% rename from docs/source/adding-interactivity/dangers-of-mutability/_examples/dict_update.py rename to docs/source/guides/adding-interactivity/dangers-of-mutability/_examples/dict_update.py diff --git a/docs/source/adding-interactivity/dangers-of-mutability/_examples/list_insert.py b/docs/source/guides/adding-interactivity/dangers-of-mutability/_examples/list_insert.py similarity index 100% rename from docs/source/adding-interactivity/dangers-of-mutability/_examples/list_insert.py rename to docs/source/guides/adding-interactivity/dangers-of-mutability/_examples/list_insert.py diff --git a/docs/source/adding-interactivity/dangers-of-mutability/_examples/list_re_order.py b/docs/source/guides/adding-interactivity/dangers-of-mutability/_examples/list_re_order.py similarity index 100% rename from docs/source/adding-interactivity/dangers-of-mutability/_examples/list_re_order.py rename to docs/source/guides/adding-interactivity/dangers-of-mutability/_examples/list_re_order.py diff --git a/docs/source/adding-interactivity/dangers-of-mutability/_examples/list_remove.py b/docs/source/guides/adding-interactivity/dangers-of-mutability/_examples/list_remove.py similarity index 100% rename from docs/source/adding-interactivity/dangers-of-mutability/_examples/list_remove.py rename to docs/source/guides/adding-interactivity/dangers-of-mutability/_examples/list_remove.py diff --git a/docs/source/adding-interactivity/dangers-of-mutability/_examples/list_replace.py b/docs/source/guides/adding-interactivity/dangers-of-mutability/_examples/list_replace.py similarity index 100% rename from docs/source/adding-interactivity/dangers-of-mutability/_examples/list_replace.py rename to docs/source/guides/adding-interactivity/dangers-of-mutability/_examples/list_replace.py diff --git a/docs/source/adding-interactivity/dangers-of-mutability/_examples/moving_dot.py b/docs/source/guides/adding-interactivity/dangers-of-mutability/_examples/moving_dot.py similarity index 100% rename from docs/source/adding-interactivity/dangers-of-mutability/_examples/moving_dot.py rename to docs/source/guides/adding-interactivity/dangers-of-mutability/_examples/moving_dot.py diff --git a/docs/source/adding-interactivity/dangers-of-mutability/_examples/moving_dot_broken.py b/docs/source/guides/adding-interactivity/dangers-of-mutability/_examples/moving_dot_broken.py similarity index 100% rename from docs/source/adding-interactivity/dangers-of-mutability/_examples/moving_dot_broken.py rename to docs/source/guides/adding-interactivity/dangers-of-mutability/_examples/moving_dot_broken.py diff --git a/docs/source/adding-interactivity/dangers-of-mutability/_examples/set_remove.py b/docs/source/guides/adding-interactivity/dangers-of-mutability/_examples/set_remove.py similarity index 100% rename from docs/source/adding-interactivity/dangers-of-mutability/_examples/set_remove.py rename to docs/source/guides/adding-interactivity/dangers-of-mutability/_examples/set_remove.py diff --git a/docs/source/adding-interactivity/dangers-of-mutability/_examples/set_update.py b/docs/source/guides/adding-interactivity/dangers-of-mutability/_examples/set_update.py similarity index 100% rename from docs/source/adding-interactivity/dangers-of-mutability/_examples/set_update.py rename to docs/source/guides/adding-interactivity/dangers-of-mutability/_examples/set_update.py diff --git a/docs/source/adding-interactivity/dangers-of-mutability/index.rst b/docs/source/guides/adding-interactivity/dangers-of-mutability/index.rst similarity index 100% rename from docs/source/adding-interactivity/dangers-of-mutability/index.rst rename to docs/source/guides/adding-interactivity/dangers-of-mutability/index.rst diff --git a/docs/source/adding-interactivity/index.rst b/docs/source/guides/adding-interactivity/index.rst similarity index 100% rename from docs/source/adding-interactivity/index.rst rename to docs/source/guides/adding-interactivity/index.rst diff --git a/docs/source/adding-interactivity/multiple-state-updates/_examples/delay_before_count_updater.py b/docs/source/guides/adding-interactivity/multiple-state-updates/_examples/delay_before_count_updater.py similarity index 100% rename from docs/source/adding-interactivity/multiple-state-updates/_examples/delay_before_count_updater.py rename to docs/source/guides/adding-interactivity/multiple-state-updates/_examples/delay_before_count_updater.py diff --git a/docs/source/adding-interactivity/multiple-state-updates/_examples/delay_before_set_count.py b/docs/source/guides/adding-interactivity/multiple-state-updates/_examples/delay_before_set_count.py similarity index 100% rename from docs/source/adding-interactivity/multiple-state-updates/_examples/delay_before_set_count.py rename to docs/source/guides/adding-interactivity/multiple-state-updates/_examples/delay_before_set_count.py diff --git a/docs/source/adding-interactivity/multiple-state-updates/_examples/set_color_3_times.py b/docs/source/guides/adding-interactivity/multiple-state-updates/_examples/set_color_3_times.py similarity index 100% rename from docs/source/adding-interactivity/multiple-state-updates/_examples/set_color_3_times.py rename to docs/source/guides/adding-interactivity/multiple-state-updates/_examples/set_color_3_times.py diff --git a/docs/source/adding-interactivity/multiple-state-updates/_examples/set_state_function.py b/docs/source/guides/adding-interactivity/multiple-state-updates/_examples/set_state_function.py similarity index 100% rename from docs/source/adding-interactivity/multiple-state-updates/_examples/set_state_function.py rename to docs/source/guides/adding-interactivity/multiple-state-updates/_examples/set_state_function.py diff --git a/docs/source/adding-interactivity/multiple-state-updates/index.rst b/docs/source/guides/adding-interactivity/multiple-state-updates/index.rst similarity index 100% rename from docs/source/adding-interactivity/multiple-state-updates/index.rst rename to docs/source/guides/adding-interactivity/multiple-state-updates/index.rst diff --git a/docs/source/adding-interactivity/responding-to-events/_examples/audio_player.py b/docs/source/guides/adding-interactivity/responding-to-events/_examples/audio_player.py similarity index 100% rename from docs/source/adding-interactivity/responding-to-events/_examples/audio_player.py rename to docs/source/guides/adding-interactivity/responding-to-events/_examples/audio_player.py diff --git a/docs/source/adding-interactivity/responding-to-events/_examples/button_async_handlers.py b/docs/source/guides/adding-interactivity/responding-to-events/_examples/button_async_handlers.py similarity index 100% rename from docs/source/adding-interactivity/responding-to-events/_examples/button_async_handlers.py rename to docs/source/guides/adding-interactivity/responding-to-events/_examples/button_async_handlers.py diff --git a/docs/source/adding-interactivity/responding-to-events/_examples/button_does_nothing.py b/docs/source/guides/adding-interactivity/responding-to-events/_examples/button_does_nothing.py similarity index 100% rename from docs/source/adding-interactivity/responding-to-events/_examples/button_does_nothing.py rename to docs/source/guides/adding-interactivity/responding-to-events/_examples/button_does_nothing.py diff --git a/docs/source/adding-interactivity/responding-to-events/_examples/button_handler_as_arg.py b/docs/source/guides/adding-interactivity/responding-to-events/_examples/button_handler_as_arg.py similarity index 100% rename from docs/source/adding-interactivity/responding-to-events/_examples/button_handler_as_arg.py rename to docs/source/guides/adding-interactivity/responding-to-events/_examples/button_handler_as_arg.py diff --git a/docs/source/adding-interactivity/responding-to-events/_examples/button_prints_event.py b/docs/source/guides/adding-interactivity/responding-to-events/_examples/button_prints_event.py similarity index 100% rename from docs/source/adding-interactivity/responding-to-events/_examples/button_prints_event.py rename to docs/source/guides/adding-interactivity/responding-to-events/_examples/button_prints_event.py diff --git a/docs/source/adding-interactivity/responding-to-events/_examples/button_prints_message.py b/docs/source/guides/adding-interactivity/responding-to-events/_examples/button_prints_message.py similarity index 100% rename from docs/source/adding-interactivity/responding-to-events/_examples/button_prints_message.py rename to docs/source/guides/adding-interactivity/responding-to-events/_examples/button_prints_message.py diff --git a/docs/source/adding-interactivity/responding-to-events/_examples/prevent_default_event_actions.py b/docs/source/guides/adding-interactivity/responding-to-events/_examples/prevent_default_event_actions.py similarity index 100% rename from docs/source/adding-interactivity/responding-to-events/_examples/prevent_default_event_actions.py rename to docs/source/guides/adding-interactivity/responding-to-events/_examples/prevent_default_event_actions.py diff --git a/docs/source/adding-interactivity/responding-to-events/_examples/stop_event_propagation.py b/docs/source/guides/adding-interactivity/responding-to-events/_examples/stop_event_propagation.py similarity index 100% rename from docs/source/adding-interactivity/responding-to-events/_examples/stop_event_propagation.py rename to docs/source/guides/adding-interactivity/responding-to-events/_examples/stop_event_propagation.py diff --git a/docs/source/adding-interactivity/responding-to-events/index.rst b/docs/source/guides/adding-interactivity/responding-to-events/index.rst similarity index 100% rename from docs/source/adding-interactivity/responding-to-events/index.rst rename to docs/source/guides/adding-interactivity/responding-to-events/index.rst diff --git a/docs/source/adding-interactivity/state-as-a-snapshot/_examples/delayed_print_after_set.py b/docs/source/guides/adding-interactivity/state-as-a-snapshot/_examples/delayed_print_after_set.py similarity index 100% rename from docs/source/adding-interactivity/state-as-a-snapshot/_examples/delayed_print_after_set.py rename to docs/source/guides/adding-interactivity/state-as-a-snapshot/_examples/delayed_print_after_set.py diff --git a/docs/source/adding-interactivity/state-as-a-snapshot/_examples/print_chat_message.py b/docs/source/guides/adding-interactivity/state-as-a-snapshot/_examples/print_chat_message.py similarity index 100% rename from docs/source/adding-interactivity/state-as-a-snapshot/_examples/print_chat_message.py rename to docs/source/guides/adding-interactivity/state-as-a-snapshot/_examples/print_chat_message.py diff --git a/docs/source/adding-interactivity/state-as-a-snapshot/_examples/print_count_after_set.py b/docs/source/guides/adding-interactivity/state-as-a-snapshot/_examples/print_count_after_set.py similarity index 100% rename from docs/source/adding-interactivity/state-as-a-snapshot/_examples/print_count_after_set.py rename to docs/source/guides/adding-interactivity/state-as-a-snapshot/_examples/print_count_after_set.py diff --git a/docs/source/adding-interactivity/state-as-a-snapshot/_examples/send_message.py b/docs/source/guides/adding-interactivity/state-as-a-snapshot/_examples/send_message.py similarity index 100% rename from docs/source/adding-interactivity/state-as-a-snapshot/_examples/send_message.py rename to docs/source/guides/adding-interactivity/state-as-a-snapshot/_examples/send_message.py diff --git a/docs/source/adding-interactivity/state-as-a-snapshot/_examples/set_counter_3_times.py b/docs/source/guides/adding-interactivity/state-as-a-snapshot/_examples/set_counter_3_times.py similarity index 100% rename from docs/source/adding-interactivity/state-as-a-snapshot/_examples/set_counter_3_times.py rename to docs/source/guides/adding-interactivity/state-as-a-snapshot/_examples/set_counter_3_times.py diff --git a/docs/source/adding-interactivity/state-as-a-snapshot/_static/direct-state-change.png b/docs/source/guides/adding-interactivity/state-as-a-snapshot/_static/direct-state-change.png similarity index 100% rename from docs/source/adding-interactivity/state-as-a-snapshot/_static/direct-state-change.png rename to docs/source/guides/adding-interactivity/state-as-a-snapshot/_static/direct-state-change.png diff --git a/docs/source/adding-interactivity/state-as-a-snapshot/_static/idom-state-change.png b/docs/source/guides/adding-interactivity/state-as-a-snapshot/_static/idom-state-change.png similarity index 100% rename from docs/source/adding-interactivity/state-as-a-snapshot/_static/idom-state-change.png rename to docs/source/guides/adding-interactivity/state-as-a-snapshot/_static/idom-state-change.png diff --git a/docs/source/adding-interactivity/state-as-a-snapshot/index.rst b/docs/source/guides/adding-interactivity/state-as-a-snapshot/index.rst similarity index 100% rename from docs/source/adding-interactivity/state-as-a-snapshot/index.rst rename to docs/source/guides/adding-interactivity/state-as-a-snapshot/index.rst diff --git a/docs/source/creating-interfaces/html-with-idom/index.rst b/docs/source/guides/creating-interfaces/html-with-idom/index.rst similarity index 98% rename from docs/source/creating-interfaces/html-with-idom/index.rst rename to docs/source/guides/creating-interfaces/html-with-idom/index.rst index 5bad18912..52ca1e617 100644 --- a/docs/source/creating-interfaces/html-with-idom/index.rst +++ b/docs/source/guides/creating-interfaces/html-with-idom/index.rst @@ -110,7 +110,7 @@ Additionally, instead of specifying ``style`` using a string, we use a dictionar .. card:: - :link: /understanding-idom/representing-html + :link: /guides/understanding-idom/representing-html :link-type: doc :octicon:`book` Read More diff --git a/docs/source/creating-interfaces/index.rst b/docs/source/guides/creating-interfaces/index.rst similarity index 100% rename from docs/source/creating-interfaces/index.rst rename to docs/source/guides/creating-interfaces/index.rst diff --git a/docs/source/creating-interfaces/rendering-data/_examples/sorted_and_filtered_todo_list.py b/docs/source/guides/creating-interfaces/rendering-data/_examples/sorted_and_filtered_todo_list.py similarity index 100% rename from docs/source/creating-interfaces/rendering-data/_examples/sorted_and_filtered_todo_list.py rename to docs/source/guides/creating-interfaces/rendering-data/_examples/sorted_and_filtered_todo_list.py diff --git a/docs/source/creating-interfaces/rendering-data/_examples/todo_from_list.py b/docs/source/guides/creating-interfaces/rendering-data/_examples/todo_from_list.py similarity index 100% rename from docs/source/creating-interfaces/rendering-data/_examples/todo_from_list.py rename to docs/source/guides/creating-interfaces/rendering-data/_examples/todo_from_list.py diff --git a/docs/source/creating-interfaces/rendering-data/_examples/todo_list_with_keys.py b/docs/source/guides/creating-interfaces/rendering-data/_examples/todo_list_with_keys.py similarity index 100% rename from docs/source/creating-interfaces/rendering-data/_examples/todo_list_with_keys.py rename to docs/source/guides/creating-interfaces/rendering-data/_examples/todo_list_with_keys.py diff --git a/docs/source/creating-interfaces/rendering-data/index.rst b/docs/source/guides/creating-interfaces/rendering-data/index.rst similarity index 98% rename from docs/source/creating-interfaces/rendering-data/index.rst rename to docs/source/guides/creating-interfaces/rendering-data/index.rst index d10aed9c3..78990bbe9 100644 --- a/docs/source/creating-interfaces/rendering-data/index.rst +++ b/docs/source/guides/creating-interfaces/rendering-data/index.rst @@ -76,7 +76,7 @@ priority. Thus, we need to change the data structure we're using to represent ou ] With this we can now imaging writing some filtering and sorting logic using Python's -:func:`filter` and :func:`sorted` functions respecitvely. We'll do this by only +:func:`filter` and :func:`sorted` functions respectively. We'll do this by only displaying items whose ``priority`` is less than or equal to some ``filter_by_priority`` and then ordering the elements based on the ``priority``: @@ -231,7 +231,7 @@ with the correct UI element. html.ul([html.li(data["text"], key=data["id"]) for data in data_2]), ) -.. dropdown:: Keys must be unique amonst siblings +.. dropdown:: Keys must be unique amongst siblings :color: danger Keys must be unique among siblings. @@ -288,7 +288,7 @@ use for each ``key``? .. card:: - :link: /understanding-idom/why-idom-needs-keys + :link: /guides/understanding-idom/why-idom-needs-keys :link-type: doc :octicon:`book` Read More diff --git a/docs/source/creating-interfaces/your-first-components/_examples/bad_conditional_todo_list.py b/docs/source/guides/creating-interfaces/your-first-components/_examples/bad_conditional_todo_list.py similarity index 100% rename from docs/source/creating-interfaces/your-first-components/_examples/bad_conditional_todo_list.py rename to docs/source/guides/creating-interfaces/your-first-components/_examples/bad_conditional_todo_list.py diff --git a/docs/source/creating-interfaces/your-first-components/_examples/good_conditional_todo_list.py b/docs/source/guides/creating-interfaces/your-first-components/_examples/good_conditional_todo_list.py similarity index 100% rename from docs/source/creating-interfaces/your-first-components/_examples/good_conditional_todo_list.py rename to docs/source/guides/creating-interfaces/your-first-components/_examples/good_conditional_todo_list.py diff --git a/docs/source/creating-interfaces/your-first-components/_examples/nested_photos.py b/docs/source/guides/creating-interfaces/your-first-components/_examples/nested_photos.py similarity index 100% rename from docs/source/creating-interfaces/your-first-components/_examples/nested_photos.py rename to docs/source/guides/creating-interfaces/your-first-components/_examples/nested_photos.py diff --git a/docs/source/creating-interfaces/your-first-components/_examples/parametrized_photos.py b/docs/source/guides/creating-interfaces/your-first-components/_examples/parametrized_photos.py similarity index 100% rename from docs/source/creating-interfaces/your-first-components/_examples/parametrized_photos.py rename to docs/source/guides/creating-interfaces/your-first-components/_examples/parametrized_photos.py diff --git a/docs/source/creating-interfaces/your-first-components/_examples/simple_photo.py b/docs/source/guides/creating-interfaces/your-first-components/_examples/simple_photo.py similarity index 100% rename from docs/source/creating-interfaces/your-first-components/_examples/simple_photo.py rename to docs/source/guides/creating-interfaces/your-first-components/_examples/simple_photo.py diff --git a/docs/source/creating-interfaces/your-first-components/_examples/todo_list.py b/docs/source/guides/creating-interfaces/your-first-components/_examples/todo_list.py similarity index 100% rename from docs/source/creating-interfaces/your-first-components/_examples/todo_list.py rename to docs/source/guides/creating-interfaces/your-first-components/_examples/todo_list.py diff --git a/docs/source/creating-interfaces/your-first-components/_examples/wrap_in_div.py b/docs/source/guides/creating-interfaces/your-first-components/_examples/wrap_in_div.py similarity index 100% rename from docs/source/creating-interfaces/your-first-components/_examples/wrap_in_div.py rename to docs/source/guides/creating-interfaces/your-first-components/_examples/wrap_in_div.py diff --git a/docs/source/creating-interfaces/your-first-components/_examples/wrap_in_fragment.py b/docs/source/guides/creating-interfaces/your-first-components/_examples/wrap_in_fragment.py similarity index 100% rename from docs/source/creating-interfaces/your-first-components/_examples/wrap_in_fragment.py rename to docs/source/guides/creating-interfaces/your-first-components/_examples/wrap_in_fragment.py diff --git a/docs/source/creating-interfaces/your-first-components/index.rst b/docs/source/guides/creating-interfaces/your-first-components/index.rst similarity index 100% rename from docs/source/creating-interfaces/your-first-components/index.rst rename to docs/source/guides/creating-interfaces/your-first-components/index.rst diff --git a/docs/source/escape-hatches/_examples/material_ui_button_no_action.py b/docs/source/guides/escape-hatches/_examples/material_ui_button_no_action.py similarity index 100% rename from docs/source/escape-hatches/_examples/material_ui_button_no_action.py rename to docs/source/guides/escape-hatches/_examples/material_ui_button_no_action.py diff --git a/docs/source/escape-hatches/_examples/material_ui_button_on_click.py b/docs/source/guides/escape-hatches/_examples/material_ui_button_on_click.py similarity index 100% rename from docs/source/escape-hatches/_examples/material_ui_button_on_click.py rename to docs/source/guides/escape-hatches/_examples/material_ui_button_on_click.py diff --git a/docs/source/escape-hatches/_examples/super_simple_chart/app.py b/docs/source/guides/escape-hatches/_examples/super_simple_chart/app.py similarity index 100% rename from docs/source/escape-hatches/_examples/super_simple_chart/app.py rename to docs/source/guides/escape-hatches/_examples/super_simple_chart/app.py diff --git a/docs/source/escape-hatches/_examples/super_simple_chart/super-simple-chart.js b/docs/source/guides/escape-hatches/_examples/super_simple_chart/super-simple-chart.js similarity index 99% rename from docs/source/escape-hatches/_examples/super_simple_chart/super-simple-chart.js rename to docs/source/guides/escape-hatches/_examples/super_simple_chart/super-simple-chart.js index f14103d78..71f117860 100644 --- a/docs/source/escape-hatches/_examples/super_simple_chart/super-simple-chart.js +++ b/docs/source/guides/escape-hatches/_examples/super_simple_chart/super-simple-chart.js @@ -8,7 +8,7 @@ export function bind(node, config) { create: (component, props, children) => h(component, props, ...children), render: (element) => render(element, node), unmount: () => render(null, node), - } + }; } export function SuperSimpleChart(props) { diff --git a/docs/source/escape-hatches/distributing-javascript.rst b/docs/source/guides/escape-hatches/distributing-javascript.rst similarity index 100% rename from docs/source/escape-hatches/distributing-javascript.rst rename to docs/source/guides/escape-hatches/distributing-javascript.rst diff --git a/docs/source/escape-hatches/index.rst b/docs/source/guides/escape-hatches/index.rst similarity index 100% rename from docs/source/escape-hatches/index.rst rename to docs/source/guides/escape-hatches/index.rst diff --git a/docs/source/escape-hatches/javascript-components.rst b/docs/source/guides/escape-hatches/javascript-components.rst similarity index 100% rename from docs/source/escape-hatches/javascript-components.rst rename to docs/source/guides/escape-hatches/javascript-components.rst diff --git a/docs/source/escape-hatches/writing-your-own-client.rst b/docs/source/guides/escape-hatches/writing-your-own-client.rst similarity index 100% rename from docs/source/escape-hatches/writing-your-own-client.rst rename to docs/source/guides/escape-hatches/writing-your-own-client.rst diff --git a/docs/source/escape-hatches/writing-your-own-server.rst b/docs/source/guides/escape-hatches/writing-your-own-server.rst similarity index 100% rename from docs/source/escape-hatches/writing-your-own-server.rst rename to docs/source/guides/escape-hatches/writing-your-own-server.rst diff --git a/docs/source/getting-started/_examples/debug_error_example.py b/docs/source/guides/getting-started/_examples/debug_error_example.py similarity index 100% rename from docs/source/getting-started/_examples/debug_error_example.py rename to docs/source/guides/getting-started/_examples/debug_error_example.py diff --git a/docs/source/getting-started/_examples/hello_world.py b/docs/source/guides/getting-started/_examples/hello_world.py similarity index 100% rename from docs/source/getting-started/_examples/hello_world.py rename to docs/source/guides/getting-started/_examples/hello_world.py diff --git a/docs/source/getting-started/_examples/sample_app.py b/docs/source/guides/getting-started/_examples/sample_app.py similarity index 100% rename from docs/source/getting-started/_examples/sample_app.py rename to docs/source/guides/getting-started/_examples/sample_app.py diff --git a/docs/source/getting-started/_static/embed-doc-ex.html b/docs/source/guides/getting-started/_static/embed-doc-ex.html similarity index 100% rename from docs/source/getting-started/_static/embed-doc-ex.html rename to docs/source/guides/getting-started/_static/embed-doc-ex.html diff --git a/docs/source/getting-started/_static/embed-idom-view/index.html b/docs/source/guides/getting-started/_static/embed-idom-view/index.html similarity index 100% rename from docs/source/getting-started/_static/embed-idom-view/index.html rename to docs/source/guides/getting-started/_static/embed-idom-view/index.html diff --git a/docs/source/getting-started/_static/embed-idom-view/main.py b/docs/source/guides/getting-started/_static/embed-idom-view/main.py similarity index 100% rename from docs/source/getting-started/_static/embed-idom-view/main.py rename to docs/source/guides/getting-started/_static/embed-idom-view/main.py diff --git a/docs/source/getting-started/_static/embed-idom-view/screenshot.png b/docs/source/guides/getting-started/_static/embed-idom-view/screenshot.png similarity index 100% rename from docs/source/getting-started/_static/embed-idom-view/screenshot.png rename to docs/source/guides/getting-started/_static/embed-idom-view/screenshot.png diff --git a/docs/source/getting-started/_static/idom-in-jupyterlab.gif b/docs/source/guides/getting-started/_static/idom-in-jupyterlab.gif similarity index 100% rename from docs/source/getting-started/_static/idom-in-jupyterlab.gif rename to docs/source/guides/getting-started/_static/idom-in-jupyterlab.gif diff --git a/docs/source/getting-started/_static/logo-django.svg b/docs/source/guides/getting-started/_static/logo-django.svg similarity index 100% rename from docs/source/getting-started/_static/logo-django.svg rename to docs/source/guides/getting-started/_static/logo-django.svg diff --git a/docs/source/getting-started/_static/logo-jupyter.svg b/docs/source/guides/getting-started/_static/logo-jupyter.svg similarity index 100% rename from docs/source/getting-started/_static/logo-jupyter.svg rename to docs/source/guides/getting-started/_static/logo-jupyter.svg diff --git a/docs/source/getting-started/_static/logo-plotly.svg b/docs/source/guides/getting-started/_static/logo-plotly.svg similarity index 100% rename from docs/source/getting-started/_static/logo-plotly.svg rename to docs/source/guides/getting-started/_static/logo-plotly.svg diff --git a/docs/source/getting-started/_static/shared-client-state-server-slider.gif b/docs/source/guides/getting-started/_static/shared-client-state-server-slider.gif similarity index 100% rename from docs/source/getting-started/_static/shared-client-state-server-slider.gif rename to docs/source/guides/getting-started/_static/shared-client-state-server-slider.gif diff --git a/docs/source/getting-started/index.rst b/docs/source/guides/getting-started/index.rst similarity index 100% rename from docs/source/getting-started/index.rst rename to docs/source/guides/getting-started/index.rst diff --git a/docs/source/getting-started/installing-idom.rst b/docs/source/guides/getting-started/installing-idom.rst similarity index 99% rename from docs/source/getting-started/installing-idom.rst rename to docs/source/guides/getting-started/installing-idom.rst index a9082972d..1187704e4 100644 --- a/docs/source/getting-started/installing-idom.rst +++ b/docs/source/guides/getting-started/installing-idom.rst @@ -105,7 +105,7 @@ are always excited to :ref:`welcome ` new contributions contributors of all kinds .. card:: - :link: /developing-idom/index + :link: /about/contributor-guide :link-type: doc :octicon:`book` Read More diff --git a/docs/source/getting-started/running-idom.rst b/docs/source/guides/getting-started/running-idom.rst similarity index 100% rename from docs/source/getting-started/running-idom.rst rename to docs/source/guides/getting-started/running-idom.rst diff --git a/docs/source/managing-state/combining-contexts-and-reducers/index.rst b/docs/source/guides/managing-state/combining-contexts-and-reducers/index.rst similarity index 100% rename from docs/source/managing-state/combining-contexts-and-reducers/index.rst rename to docs/source/guides/managing-state/combining-contexts-and-reducers/index.rst diff --git a/docs/source/managing-state/deeply-sharing-state-with-contexts/index.rst b/docs/source/guides/managing-state/deeply-sharing-state-with-contexts/index.rst similarity index 100% rename from docs/source/managing-state/deeply-sharing-state-with-contexts/index.rst rename to docs/source/guides/managing-state/deeply-sharing-state-with-contexts/index.rst diff --git a/docs/source/managing-state/how-to-structure-state/index.rst b/docs/source/guides/managing-state/how-to-structure-state/index.rst similarity index 100% rename from docs/source/managing-state/how-to-structure-state/index.rst rename to docs/source/guides/managing-state/how-to-structure-state/index.rst diff --git a/docs/source/managing-state/index.rst b/docs/source/guides/managing-state/index.rst similarity index 100% rename from docs/source/managing-state/index.rst rename to docs/source/guides/managing-state/index.rst diff --git a/docs/source/managing-state/sharing-component-state/_examples/filterable_list/app.py b/docs/source/guides/managing-state/sharing-component-state/_examples/filterable_list/app.py similarity index 100% rename from docs/source/managing-state/sharing-component-state/_examples/filterable_list/app.py rename to docs/source/guides/managing-state/sharing-component-state/_examples/filterable_list/app.py diff --git a/docs/source/managing-state/sharing-component-state/_examples/filterable_list/data.json b/docs/source/guides/managing-state/sharing-component-state/_examples/filterable_list/data.json similarity index 100% rename from docs/source/managing-state/sharing-component-state/_examples/filterable_list/data.json rename to docs/source/guides/managing-state/sharing-component-state/_examples/filterable_list/data.json diff --git a/docs/source/managing-state/sharing-component-state/_examples/synced_inputs/app.py b/docs/source/guides/managing-state/sharing-component-state/_examples/synced_inputs/app.py similarity index 100% rename from docs/source/managing-state/sharing-component-state/_examples/synced_inputs/app.py rename to docs/source/guides/managing-state/sharing-component-state/_examples/synced_inputs/app.py diff --git a/docs/source/managing-state/sharing-component-state/index.rst b/docs/source/guides/managing-state/sharing-component-state/index.rst similarity index 100% rename from docs/source/managing-state/sharing-component-state/index.rst rename to docs/source/guides/managing-state/sharing-component-state/index.rst diff --git a/docs/source/managing-state/simplifying-updates-with-reducers/index.rst b/docs/source/guides/managing-state/simplifying-updates-with-reducers/index.rst similarity index 100% rename from docs/source/managing-state/simplifying-updates-with-reducers/index.rst rename to docs/source/guides/managing-state/simplifying-updates-with-reducers/index.rst diff --git a/docs/source/managing-state/when-and-how-to-reset-state/index.rst b/docs/source/guides/managing-state/when-and-how-to-reset-state/index.rst similarity index 100% rename from docs/source/managing-state/when-and-how-to-reset-state/index.rst rename to docs/source/guides/managing-state/when-and-how-to-reset-state/index.rst diff --git a/docs/source/understanding-idom/_static/idom-flow-diagram.svg b/docs/source/guides/understanding-idom/_static/idom-flow-diagram.svg similarity index 100% rename from docs/source/understanding-idom/_static/idom-flow-diagram.svg rename to docs/source/guides/understanding-idom/_static/idom-flow-diagram.svg diff --git a/docs/source/understanding-idom/_static/live-examples-in-docs.gif b/docs/source/guides/understanding-idom/_static/live-examples-in-docs.gif similarity index 100% rename from docs/source/understanding-idom/_static/live-examples-in-docs.gif rename to docs/source/guides/understanding-idom/_static/live-examples-in-docs.gif diff --git a/docs/source/understanding-idom/_static/mvc-flow-diagram.svg b/docs/source/guides/understanding-idom/_static/mvc-flow-diagram.svg similarity index 100% rename from docs/source/understanding-idom/_static/mvc-flow-diagram.svg rename to docs/source/guides/understanding-idom/_static/mvc-flow-diagram.svg diff --git a/docs/source/understanding-idom/_static/npm-download-trends.png b/docs/source/guides/understanding-idom/_static/npm-download-trends.png similarity index 100% rename from docs/source/understanding-idom/_static/npm-download-trends.png rename to docs/source/guides/understanding-idom/_static/npm-download-trends.png diff --git a/docs/source/understanding-idom/index.rst b/docs/source/guides/understanding-idom/index.rst similarity index 85% rename from docs/source/understanding-idom/index.rst rename to docs/source/guides/understanding-idom/index.rst index 4c0baaf2a..389995553 100644 --- a/docs/source/understanding-idom/index.rst +++ b/docs/source/guides/understanding-idom/index.rst @@ -11,3 +11,7 @@ Understanding IDOM the-rendering-process layout-render-servers writing-tests + +.. note:: + + Under construction ๐Ÿšง diff --git a/docs/source/understanding-idom/layout-render-servers.rst b/docs/source/guides/understanding-idom/layout-render-servers.rst similarity index 100% rename from docs/source/understanding-idom/layout-render-servers.rst rename to docs/source/guides/understanding-idom/layout-render-servers.rst diff --git a/docs/source/understanding-idom/representing-html.rst b/docs/source/guides/understanding-idom/representing-html.rst similarity index 100% rename from docs/source/understanding-idom/representing-html.rst rename to docs/source/guides/understanding-idom/representing-html.rst diff --git a/docs/source/understanding-idom/the-rendering-pipeline.rst b/docs/source/guides/understanding-idom/the-rendering-pipeline.rst similarity index 100% rename from docs/source/understanding-idom/the-rendering-pipeline.rst rename to docs/source/guides/understanding-idom/the-rendering-pipeline.rst diff --git a/docs/source/understanding-idom/the-rendering-process.rst b/docs/source/guides/understanding-idom/the-rendering-process.rst similarity index 100% rename from docs/source/understanding-idom/the-rendering-process.rst rename to docs/source/guides/understanding-idom/the-rendering-process.rst diff --git a/docs/source/understanding-idom/what-are-components.rst b/docs/source/guides/understanding-idom/what-are-components.rst similarity index 100% rename from docs/source/understanding-idom/what-are-components.rst rename to docs/source/guides/understanding-idom/what-are-components.rst diff --git a/docs/source/understanding-idom/why-idom-needs-keys.rst b/docs/source/guides/understanding-idom/why-idom-needs-keys.rst similarity index 100% rename from docs/source/understanding-idom/why-idom-needs-keys.rst rename to docs/source/guides/understanding-idom/why-idom-needs-keys.rst diff --git a/docs/source/understanding-idom/writing-tests.rst b/docs/source/guides/understanding-idom/writing-tests.rst similarity index 100% rename from docs/source/understanding-idom/writing-tests.rst rename to docs/source/guides/understanding-idom/writing-tests.rst diff --git a/docs/source/index.rst b/docs/source/index.rst index 516a33a25..1a48693f9 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -9,30 +9,34 @@ What is IDOM? .. toctree:: :hidden: - :caption: User Guide + :caption: Guides - getting-started/index - creating-interfaces/index - adding-interactivity/index - managing-state/index - escape-hatches/index - understanding-idom/index + guides/getting-started/index + guides/creating-interfaces/index + guides/adding-interactivity/index + guides/managing-state/index + guides/escape-hatches/index + guides/understanding-idom/index .. toctree:: :hidden: - :caption: Other Resources + :caption: Reference - developing-idom/index - reference-material/index - credits-and-licenses + reference/browser-events + reference/hooks-api + _auto/apis + reference/javascript-api + reference/specifications .. toctree:: :hidden: - :caption: External Links + :caption: About + about/changelog + about/contributor-guide + about/credits-and-licenses Source Code Community - Issues IDOM is a Python web framework for building **interactive websites without needing a @@ -56,7 +60,7 @@ At a Glance To get a rough idea of how to write apps in IDOM, take a look at the tiny `"hello world" `__ application below: -.. idom:: getting-started/_examples/hello_world +.. idom:: guides/getting-started/_examples/hello_world .. hint:: @@ -101,10 +105,10 @@ IDOM within a Jupyter Notebook, this is where you can learn how to do those thin .. grid-item:: - .. image:: getting-started/_static/idom-in-jupyterlab.gif + .. image:: guides/getting-started/_static/idom-in-jupyterlab.gif .. card:: - :link: getting-started/index + :link: guides/getting-started/index :link-type: doc :octicon:`book` Read More @@ -123,10 +127,10 @@ combine these elements into reusable :ref:`"components" ` sections that follow you'll learn how these UI elements are created and organized into components. Then, you'll use this knowledge to create interfaces from raw data: -.. idom:: creating-interfaces/rendering-data/_examples/todo_list_with_keys +.. idom:: guides/creating-interfaces/rendering-data/_examples/todo_list_with_keys .. card:: - :link: creating-interfaces/index + :link: guides/creating-interfaces/index :link-type: doc :octicon:`book` Read More @@ -146,7 +150,7 @@ image, the shopping cart. In IDOM, this kind of component-specific memory is cre updated with a "hook" called ``use_state()`` that creates a **state variable** and **state setter** respectively: -.. idom:: adding-interactivity/components-with-state/_examples/adding_state_variable +.. idom:: guides/adding-interactivity/components-with-state/_examples/adding_state_variable In IDOM, ``use_state``, as well as any other function whose name starts with ``use``, is called a "hook". These are special functions that should only be called while IDOM is @@ -155,7 +159,7 @@ capabilities of IDOM's components of which ``use_state`` is just one (well get i other :ref:`later `). .. card:: - :link: adding-interactivity/index + :link: guides/adding-interactivity/index :link-type: doc :octicon:`book` Read More @@ -168,7 +172,7 @@ Chapter 4 - :ref:`Managing State` --------------------------------- .. card:: - :link: managing-state/index + :link: guides/managing-state/index :link-type: doc :octicon:`book` Read More @@ -182,7 +186,7 @@ Chapter 5 - :ref:`Escape Hatches` --------------------------------- .. card:: - :link: escape-hatches/index + :link: guides/escape-hatches/index :link-type: doc :octicon:`book` Read More @@ -195,7 +199,7 @@ Chapter 6 - :ref:`Understanding IDOM` ------------------------------------- .. card:: - :link: escape-hatches/index + :link: guides/escape-hatches/index :link-type: doc :octicon:`book` Read More diff --git a/docs/source/reference-material/examples.rst b/docs/source/reference-material/examples.rst deleted file mode 100644 index 694864e53..000000000 --- a/docs/source/reference-material/examples.rst +++ /dev/null @@ -1,106 +0,0 @@ -Examples -======== - -Slideshow ---------- - -Try clicking the image ๐Ÿ–ฑ๏ธ - -.. idom:: _examples/slideshow - :result-is-default-tab: - - -Click Counter -------------- - -.. idom:: _examples/click_count - :result-is-default-tab: - - -To Do List ----------- - -Try typing in the text box and pressing 'Enter' ๐Ÿ“‹ - -.. idom:: _examples/todo - :result-is-default-tab: - - -Simple Image Movement ---------------------- - -.. idom:: _examples/character_movement - :result-is-default-tab: - - -The Game Snake --------------- - -Click to start playing and use the arrow keys to move ๐ŸŽฎ - -Slow internet may cause inconsistent frame pacing ๐Ÿ˜… - -.. idom:: _examples/snake_game - :result-is-default-tab: - - -Matplotlib Plot ---------------- - -Pick the polynomial coefficients (separate each coefficient by a space) ๐Ÿ”ข: - -.. idom:: _examples/matplotlib_plot - :result-is-default-tab: - - -Simple Dashboard ----------------- - -Try interacting with the sliders ๐Ÿ“ˆ - -.. idom:: _examples/simple_dashboard - :result-is-default-tab: - - -Dynamically Loaded React Components ------------------------------------ - -This method is not recommended for use in production applications, but it's great while -you're experimenting: - -.. idom:: _examples/victory_chart - :result-is-default-tab: - - -Material UI Button ------------------- - -Click the button to change the indicator ๐Ÿ‘‡ - -.. idom:: _examples/material_ui_switch - :result-is-default-tab: - - -Pigeon Maps ------------ - -Click the map to create pinned location ๐Ÿ“: - -.. idom:: _examples/pigeon_maps - :result-is-default-tab: - - -Cytoscape Network Graph ------------------------ - -You can move the nodes in the graph ๐Ÿ•ธ๏ธ: - -.. idom:: _examples/network_graph - :result-is-default-tab: - - -.. Links -.. ===== - -.. |launch-binder| image:: https://mybinder.org/badge_logo.svg - :target: https://mybinder.org/v2/gh/idom-team/idom-jupyter/main?filepath=examples%2Fintroduction.ipynb diff --git a/docs/source/reference-material/faq.rst b/docs/source/reference-material/faq.rst deleted file mode 100644 index df1628dcd..000000000 --- a/docs/source/reference-material/faq.rst +++ /dev/null @@ -1,64 +0,0 @@ -FAQ -=== - -See our :discussion-type:`Discussion Forum ` for more questions and answers. - - -Do UI components run client-side? ---------------------------------- - -No. The layout is constructed, and components are executed, server-side in Python. Only -rendering occurs client-side. This means you can access files, databases, and all your -favorite Python packages with IDOM. - - -Does IDOM transpile Python to Javascript? ------------------------------------------ - -No. As in the answer to :ref:`Do UI components run client-side?`, IDOM runs almost -everything server-side and in Python. This was an explicit design choice to keep things -simple and one which allows you to do everything you normally would in Python. - - -Does IDOM support any React component? --------------------------------------- - -If you use :ref:`Dynamically Loaded Components`, then the answer is no. Only components -whose props are JSON serializable, or which expect basic callback functions similar to -those of standard event handlers (e.g. ``onClick``) will operate as expected. - -However, if you import a :ref:`Custom Javascript Component ` -then, so long as the bundle has be defined appropriately, any component can be made to -work, even those that don't rely on React. - - -How does IDOM communicate with the client? ------------------------------------------- - -IDOM sends diffs of a Virtual Document Object Model (:ref:`VDOM`) to the -client. For more details, see the description in -`this article `__. - - -Can I use Javascript components from a CDN? -------------------------------------------- - -Yes, but with some restrictions: - -1. The Javascript in question must be distributed as an ECMAScript Module - (`ESM `__) -2. The module must export the :ref:`required interface `. - -These restrictions apply because the Javascript from the CDN must be able to run -natively in the browser and the module must be able to run in isolation from the main -application. - -See :ref:`Distributing Javascript via CDN_` for more info. - - -What props can I pass to Javascript components? ------------------------------------------------ - -You can only pass JSON serializable props to components implemented in Javascript. It is -possible to create a :ref:`Custom Javascript Component ` -which undestands how to deserialise JSON data into native Javascript objects though. diff --git a/docs/source/reference-material/index.rst b/docs/source/reference-material/index.rst deleted file mode 100644 index fb4021aca..000000000 --- a/docs/source/reference-material/index.rst +++ /dev/null @@ -1,17 +0,0 @@ -Reference Material -================== - -.. toctree:: - :hidden: - - examples - hooks-api - /_auto/apis - javascript-api - browser-events - specifications - faq - -.. note:: - - Under construction ๐Ÿšง diff --git a/docs/source/reference-material/_examples/character_movement/app.py b/docs/source/reference/_examples/character_movement/app.py similarity index 100% rename from docs/source/reference-material/_examples/character_movement/app.py rename to docs/source/reference/_examples/character_movement/app.py diff --git a/docs/source/reference-material/_examples/character_movement/static/bunny.png b/docs/source/reference/_examples/character_movement/static/bunny.png similarity index 100% rename from docs/source/reference-material/_examples/character_movement/static/bunny.png rename to docs/source/reference/_examples/character_movement/static/bunny.png diff --git a/docs/source/reference-material/_examples/click_count.py b/docs/source/reference/_examples/click_count.py similarity index 100% rename from docs/source/reference-material/_examples/click_count.py rename to docs/source/reference/_examples/click_count.py diff --git a/docs/source/reference-material/_examples/material_ui_switch.py b/docs/source/reference/_examples/material_ui_switch.py similarity index 100% rename from docs/source/reference-material/_examples/material_ui_switch.py rename to docs/source/reference/_examples/material_ui_switch.py diff --git a/docs/source/reference-material/_examples/matplotlib_plot.py b/docs/source/reference/_examples/matplotlib_plot.py similarity index 100% rename from docs/source/reference-material/_examples/matplotlib_plot.py rename to docs/source/reference/_examples/matplotlib_plot.py diff --git a/docs/source/reference-material/_examples/network_graph.py b/docs/source/reference/_examples/network_graph.py similarity index 100% rename from docs/source/reference-material/_examples/network_graph.py rename to docs/source/reference/_examples/network_graph.py diff --git a/docs/source/reference-material/_examples/pigeon_maps.py b/docs/source/reference/_examples/pigeon_maps.py similarity index 100% rename from docs/source/reference-material/_examples/pigeon_maps.py rename to docs/source/reference/_examples/pigeon_maps.py diff --git a/docs/source/reference-material/_examples/simple_dashboard.py b/docs/source/reference/_examples/simple_dashboard.py similarity index 100% rename from docs/source/reference-material/_examples/simple_dashboard.py rename to docs/source/reference/_examples/simple_dashboard.py diff --git a/docs/source/reference-material/_examples/slideshow.py b/docs/source/reference/_examples/slideshow.py similarity index 100% rename from docs/source/reference-material/_examples/slideshow.py rename to docs/source/reference/_examples/slideshow.py diff --git a/docs/source/reference-material/_examples/snake_game.py b/docs/source/reference/_examples/snake_game.py similarity index 100% rename from docs/source/reference-material/_examples/snake_game.py rename to docs/source/reference/_examples/snake_game.py diff --git a/docs/source/reference-material/_examples/todo.py b/docs/source/reference/_examples/todo.py similarity index 100% rename from docs/source/reference-material/_examples/todo.py rename to docs/source/reference/_examples/todo.py diff --git a/docs/source/reference-material/_examples/use_reducer_counter.py b/docs/source/reference/_examples/use_reducer_counter.py similarity index 100% rename from docs/source/reference-material/_examples/use_reducer_counter.py rename to docs/source/reference/_examples/use_reducer_counter.py diff --git a/docs/source/reference-material/_examples/use_state_counter.py b/docs/source/reference/_examples/use_state_counter.py similarity index 100% rename from docs/source/reference-material/_examples/use_state_counter.py rename to docs/source/reference/_examples/use_state_counter.py diff --git a/docs/source/reference-material/_examples/victory_chart.py b/docs/source/reference/_examples/victory_chart.py similarity index 100% rename from docs/source/reference-material/_examples/victory_chart.py rename to docs/source/reference/_examples/victory_chart.py diff --git a/docs/source/reference-material/_static/vdom-json-schema.json b/docs/source/reference/_static/vdom-json-schema.json similarity index 84% rename from docs/source/reference-material/_static/vdom-json-schema.json rename to docs/source/reference/_static/vdom-json-schema.json index d3ab5bd6d..2281657e3 100644 --- a/docs/source/reference-material/_static/vdom-json-schema.json +++ b/docs/source/reference/_static/vdom-json-schema.json @@ -35,9 +35,7 @@ "type": "string" } }, - "required": [ - "tagName" - ], + "required": ["tagName"], "type": "object" }, "elementChildren": { @@ -61,10 +59,7 @@ "then": { "$ref": "#/definitions/element" }, - "type": [ - "object", - "string" - ] + "type": ["object", "string"] }, "eventHander": { "properties": { @@ -78,9 +73,7 @@ "type": "string" } }, - "required": [ - "target" - ], + "required": ["target"], "type": "object" }, "importSource": { @@ -94,29 +87,20 @@ "then": { "$ref": "#/definitions/elementOrString" }, - "type": [ - "object", - "string", - "null" - ] + "type": ["object", "string", "null"] }, "source": { "type": "string" }, "sourceType": { - "enum": [ - "URL", - "NAME" - ] + "enum": ["URL", "NAME"] }, "unmountBeforeUpdate": { "type": "boolean" } }, - "required": [ - "source" - ], + "required": ["source"], "type": "object" } } -} \ No newline at end of file +} diff --git a/docs/source/reference-material/browser-events.rst b/docs/source/reference/browser-events.rst similarity index 100% rename from docs/source/reference-material/browser-events.rst rename to docs/source/reference/browser-events.rst diff --git a/docs/source/reference-material/hooks-api.rst b/docs/source/reference/hooks-api.rst similarity index 98% rename from docs/source/reference-material/hooks-api.rst rename to docs/source/reference/hooks-api.rst index f41a532cf..286508a6c 100644 --- a/docs/source/reference-material/hooks-api.rst +++ b/docs/source/reference/hooks-api.rst @@ -164,11 +164,11 @@ supports ``async`` functions: .. code-block:: - async def nonblocking_effect(): + async def non_blocking_effect(): resource = await do_something_asynchronously() return lambda: blocking_close(resource) - use_effect(nonblocking_effect) + use_effect(non_blocking_effect) There are **three important subtleties** to note about using asynchronous effects: @@ -311,7 +311,6 @@ The identity of the ``Ref`` object will be preserved for the lifetime of the com A ``Ref`` is most useful if you need to incur side effects since updating its ``.current`` attribute doesn't trigger a re-render of the component. You'll often use this hook alongside :ref:`Use Effect` or in response to component event handlers. -:ref:`The Game Snake` provides a good use case for ``use_ref``. .. links diff --git a/docs/source/reference-material/javascript-api.rst b/docs/source/reference/javascript-api.rst similarity index 100% rename from docs/source/reference-material/javascript-api.rst rename to docs/source/reference/javascript-api.rst diff --git a/docs/source/reference-material/specifications.rst b/docs/source/reference/specifications.rst similarity index 100% rename from docs/source/reference-material/specifications.rst rename to docs/source/reference/specifications.rst diff --git a/scripts/update_versions.py b/scripts/update_versions.py index 5da160625..b9ba5dd97 100644 --- a/scripts/update_versions.py +++ b/scripts/update_versions.py @@ -11,7 +11,7 @@ JS_PACKAGE_JSON_FILES = [ pkg_dir / "package.json" for pkg_dir in (JS_ROOT_DIR / "packages").iterdir() ] + [JS_ROOT_DIR / "package.json"] - +CHANGELOG_FILE = ROOT / "docs" / "source" / "about" / "changelog.rst" VERSION_INFO = semver.VersionInfo.parse(VERSION_FILE.read_text().strip()) @@ -19,6 +19,7 @@ def main() -> None: version_str = str(VERSION_INFO) update_py_version(version_str) update_js_versions(version_str) + update_changelog_version(version_str) def update_py_version(new_version: str) -> None: @@ -40,5 +41,38 @@ def update_js_versions(new_version: str) -> None: pkg_json_file.write_text(json.dumps(pkg_json, indent=2, sort_keys=True) + "\n") +def update_changelog_version(new_version: str) -> None: + old_content = CHANGELOG_FILE.read_text().split("\n") + + new_content = [] + for index in range(0, len(old_content), 2): + if index == len(old_content) - 2: + # reached end of file + continue + + old_lines = old_content[index : index + 2] + if old_lines[0] == "Unreleased" and old_lines[1] == ("-" * len(old_lines[0])): + new_content.append(_UNRELEASED_SECTION) + new_content.append(new_version) + new_content.append("-" * len(new_version)) + new_content.extend(old_content[index + 2 :]) + break + else: + new_content.extend(old_lines) + else: + raise ValueError(f"Did not find 'Unreleased' section in {CHANGELOG_FILE}") + + CHANGELOG_FILE.write_text("\n".join(new_content)) + + +_UNRELEASED_SECTION = """\ +Unreleased +---------- + +Nothing yet... + +""" + + if __name__ == "__main__": main()