diff --git a/.github/workflows/test-docs.yml b/.github/workflows/test-docs.yml index 228e4fca..3bbacf4f 100644 --- a/.github/workflows/test-docs.yml +++ b/.github/workflows/test-docs.yml @@ -1,25 +1,25 @@ name: Test on: - push: - branches: - - main - pull_request: - branches: - - main - schedule: - - cron: "0 0 * * *" + push: + branches: + - main + pull_request: + branches: + - main + schedule: + - cron: "0 0 * * *" jobs: - docs: - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@v3 - with: - fetch-depth: 0 - - uses: actions/setup-python@v4 - with: - python-version: 3.x - - run: pip install -r requirements/build-docs.txt - - run: linkcheckMarkdown docs/ -v -r - - run: mkdocs build --verbose + docs: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v3 + with: + fetch-depth: 0 + - uses: actions/setup-python@v4 + with: + python-version: 3.x + - run: pip install -r requirements/build-docs.txt + - run: linkcheckMarkdown docs/ -v -r + - run: mkdocs build --verbose --strict diff --git a/CHANGELOG.md b/CHANGELOG.md index cab02d0e..9e0b8d57 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -26,16 +26,16 @@ Using the following categories, list your changes in this order: ## [2.1.0] - 2022-11-01 -## Changed +### Changed - Minimum `channels` version is now `4.0.0`. ### Fixed - Change type hint on `view_to_component` callable to have `request` argument be optional. -- Change type hint on `view_to_component` to represent it as a decorator with paranthesis (ex `@view_to_component(compatibility=True)`) +- Change type hint on `view_to_component` to represent it as a decorator with parenthesis (such as `@view_to_component(compatibility=True)`) -## Security +### Security - Add note to docs about potential information exposure via `view_to_component` when using `compatibility=True`. @@ -137,7 +137,7 @@ Using the following categories, list your changes in this order: - Ability to declare the HTML class of the top-level component `div` - `name = ...` parameter to IDOM HTTP paths for use with `django.urls.reverse()` -- Cache versioning to automatically invalidate old web module files from the cache backend +- Cache versioning to automatically invalidate old web module files from the cache back-end - Automatic pre-population of the IDOM component registry - Type hinting for `IdomWebsocket` @@ -153,7 +153,7 @@ Using the following categories, list your changes in this order: - `IDOM_WEB_MODULES_PATH` has been replaced with Django `include(...)` - `IDOM_WS_MAX_RECONNECT_DELAY` has been renamed to `IDOM_WS_MAX_RECONNECT_TIMEOUT` -- `idom_web_modules` cache backend has been renamed to `idom` +- `idom_web_modules` cache back-end has been renamed to `idom` ### Fixed @@ -162,7 +162,7 @@ Using the following categories, list your changes in this order: ### Security -- Fixed potential directory travesal attack on the IDOM web modules URL +- Fixed potential directory traversal attack on the IDOM web modules URL ## [0.0.1] - 2021-08-18 diff --git a/README.md b/README.md index 1c7e4fbc..3f06594a 100644 --- a/README.md +++ b/README.md @@ -5,7 +5,7 @@ -Django-IDOM connects your Python project to a ReactJS frontend, allowing you to create **interactive websites without needing JavaScript!** +Django-IDOM connects your Python project to a ReactJS front-end, allowing you to create **interactive websites without needing JavaScript!** Following ReactJS styling, web elements are combined into [reusable "components"](https://idom-docs.herokuapp.com/docs/guides/creating-interfaces/your-first-components/index.html#parametrizing-components). These components can utilize [hooks](https://idom-docs.herokuapp.com/docs/reference/hooks-api.html) and [events](https://idom-docs.herokuapp.com/docs/guides/adding-interactivity/responding-to-events/index.html#async-event-handlers) to create infinitely complex web pages. @@ -25,7 +25,7 @@ Any Python web framework with Websockets can support IDOM. See below for what fr -You'll need a file to define your [IDOM](https://github.com/idom-team/idom) components. We recommend creating a `components.py` file within your chosen **Django app** to start out. Within this file, we will create a simple `hello_world` component. +You will need a file to define your [IDOM](https://github.com/idom-team/idom) components. We recommend creating a `components.py` file within your chosen **Django app** to start out. Within this file, we will create a simple `hello_world` component. @@ -46,7 +46,7 @@ def hello_world(recipient: str): In your **Django app**'s HTML template, you can now embed your IDOM component using the `component` template tag. Within this tag, you will need to type in your dotted path to the component function as the first argument. -Additonally, you can pass in keyword arguments into your component function. For example, after reading the code below, pay attention to how the function definition for `hello_world` (_in the previous example_) accepts a `recipient` argument. +Additionally, you can pass in keyword arguments into your component function. For example, after reading the code below, pay attention to how the function definition for `hello_world` (_in the previous example_) accepts a `recipient` argument. diff --git a/docs/src/contribute/code.md b/docs/src/contribute/code.md index 3f3d7aee..2a6b9feb 100644 --- a/docs/src/contribute/code.md +++ b/docs/src/contribute/code.md @@ -2,7 +2,7 @@ Everything within the `django-idom` repository must be specific to Django integration. Check out the [IDOM Core documentation](https://idom-docs.herokuapp.com/docs/about/contributor-guide.html) to contribute general features such as: components, hooks, events, and more. -If you plan to make code changes to this repository, you'll need to install the following dependencies first: +If you plan to make code changes to this repository, you will need to install the following dependencies first: - [Python 3.8+](https://www.python.org/downloads/) - [Git](https://git-scm.com/downloads) diff --git a/docs/src/contribute/docs.md b/docs/src/contribute/docs.md index 231fb603..d918c4b9 100644 --- a/docs/src/contribute/docs.md +++ b/docs/src/contribute/docs.md @@ -1,4 +1,4 @@ -If you plan to make changes to this documentation, you'll need to install the following dependencies first: +If you plan to make changes to this documentation, you will need to install the following dependencies first: - [Python 3.8+](https://www.python.org/downloads/) - [Git](https://git-scm.com/downloads) diff --git a/docs/src/contribute/running-tests.md b/docs/src/contribute/running-tests.md index f1ff6cc1..8f806e08 100644 --- a/docs/src/contribute/running-tests.md +++ b/docs/src/contribute/running-tests.md @@ -1,6 +1,6 @@ -This repo uses [Nox](https://nox.thea.codes/en/stable/) to run tests. For a full test of available scripts run `nox -l`. +This repository uses [Nox](https://nox.thea.codes/en/stable/) to run tests. For a full test of available scripts run `nox -l`. -If you plan to run tests, you'll need to install the following dependencies first: +If you plan to run tests, you will need to install the following dependencies first: - [Python 3.8+](https://www.python.org/downloads/) - [Git](https://git-scm.com/downloads) diff --git a/docs/src/dictionary.txt b/docs/src/dictionary.txt new file mode 100644 index 00000000..3e4179a1 --- /dev/null +++ b/docs/src/dictionary.txt @@ -0,0 +1,24 @@ +django +nox +websocket +websockets +changelog +async +pre +prefetch +preloader +whitespace +refetch +refetched +refetching +html +jupyter +webserver +iframe +keyworded +stylesheet +stylesheets +unstyled +py +idom +asgi diff --git a/docs/src/features/components.md b/docs/src/features/components.md index eca86f66..019f03b7 100644 --- a/docs/src/features/components.md +++ b/docs/src/features/components.md @@ -4,7 +4,7 @@ ## View To Component -Convert any Django view into a IDOM component by usng this decorator. Compatible with [Function Based Views](https://docs.djangoproject.com/en/dev/topics/http/views/) and [Class Based Views](https://docs.djangoproject.com/en/dev/topics/class-based-views/). Views can be sync or async. +Convert any Django view into a IDOM component by using this decorator. Compatible with [Function Based Views](https://docs.djangoproject.com/en/dev/topics/http/views/) and [Class Based Views](https://docs.djangoproject.com/en/dev/topics/class-based-views/). Views can be sync or async. === "components.py" @@ -30,10 +30,10 @@ Convert any Django view into a IDOM component by usng this decorator. Compatible | Name | Type | Description | Default | | --- | --- | --- | --- | - | view | `Callable | View` | The view function or class to convert. | N/A | - | compatibility | `bool` | If True, the component will be rendered in an iframe. When using compatibility mode `tranforms`, `strict_parsing`, `request`, `args`, and `kwargs` arguments will be ignored. | `False` | - | transforms | `Sequence[Callable[[VdomDict], Any]]` | A list of functions that transforms the newly generated VDOM. The functions will be called on each VDOM node. | `tuple` | - | strict_parsing | `bool` | If True, an exception will be generated if the HTML does not perfectly adhere to HTML5. | `True` | + | `view` | `Callable | View` | The view function or class to convert. | N/A | + | `compatibility` | `bool` | If True, the component will be rendered in an iframe. When using compatibility mode `tranforms`, `strict_parsing`, `request`, `args`, and `kwargs` arguments will be ignored. | `False` | + | `transforms` | `Sequence[Callable[[VdomDict], Any]]` | A list of functions that transforms the newly generated VDOM. The functions will be called on each VDOM node. | `tuple` | + | `strict_parsing` | `bool` | If True, an exception will be generated if the HTML does not perfectly adhere to HTML5. | `True` | **Returns** @@ -45,9 +45,9 @@ Convert any Django view into a IDOM component by usng this decorator. Compatible When using `compatibility` mode, IDOM automatically exposes a URL to your view. - It is your responsibility to ensure priveledged information is not leaked via this method. + It is your responsibility to ensure privileged information is not leaked via this method. - This can be done via directly writing conditionals into your view, or by adding decorators such as [user_passes_test](https://docs.djangoproject.com/en/dev/topics/auth/default/#django.contrib.auth.decorators.user_passes_test) to your views prior to using `view_to_component`. + This can be done via directly writing conditionals into your view, or by adding decorators such as [`user_passes_test`](https://docs.djangoproject.com/en/dev/topics/auth/default/#django.contrib.auth.decorators.user_passes_test) to your views prior to using `view_to_component`. === "Function Based View" @@ -78,7 +78,7 @@ Convert any Django view into a IDOM component by usng this decorator. Compatible - Requires manual intervention to change request methods beyond `GET`. - IDOM events cannot conveniently be attached to converted view HTML. - Does not currently load any HTML contained with a `` tag - - Has no option to automatically intercept local anchor link (ex. `#!html `) click events + - Has no option to automatically intercept local anchor link (such as `#!html `) click events _Please note these limitations do not exist when using `compatibility` mode._ @@ -303,8 +303,8 @@ Allows you to defer loading a CSS stylesheet until a component begins rendering. | Name | Type | Description | Default | | --- | --- | --- | --- | - | static_path | `str` | The path to the static file. This path is identical to what you would use on a `static` template tag. | N/A | - | key | `Key | None` | A key to uniquely identify this component which is unique amongst a component's immediate siblings | `None` | + | `static_path` | `str` | The path to the static file. This path is identical to what you would use on a `static` template tag. | N/A | + | `key` | `Key | None` | A key to uniquely identify this component which is unique amongst a component's immediate siblings | `None` | **Returns** @@ -318,7 +318,7 @@ Allows you to defer loading a CSS stylesheet until a component begins rendering. ??? question "Can I load static CSS using `html.link` instead?" - While you can load stylesheets with `html.link`, keep in mind that loading this way **does not** ensure load order. Thus, your stylesheet will be loaded after your component is displayed. This would likely cause some visual jankiness, so use this at your own discretion. + While you can load stylesheets with `html.link`, keep in mind that loading this way **does not** ensure load order. Thus, your stylesheet will be loaded after your component is displayed. This would likely cause unintended visual behavior, so use this at your own discretion. Here's an example on what you should avoid doing for Django static files: @@ -381,8 +381,8 @@ Allows you to defer loading JavaScript until a component begins rendering. This | Name | Type | Description | Default | | --- | --- | --- | --- | - | static_path | `str` | The path to the static file. This path is identical to what you would use on a `static` template tag. | N/A | - | key | `Key | None` | A key to uniquely identify this component which is unique amongst a component's immediate siblings | `None` | + | `static_path` | `str` | The path to the static file. This path is identical to what you would use on a `static` template tag. | N/A | + | `key` | `Key | None` | A key to uniquely identify this component which is unique amongst a component's immediate siblings | `None` | **Returns** diff --git a/docs/src/features/decorators.md b/docs/src/features/decorators.md index 8b28c08a..663dfb52 100644 --- a/docs/src/features/decorators.md +++ b/docs/src/features/decorators.md @@ -31,8 +31,8 @@ This decorator can be used with or without parentheses. | Name | Type | Description | Default | | --- | --- | --- | --- | - | auth_attribute | `str` | The value to check within the user object. This is checked in the form of `UserModel.`. | `#!python "is_active"` | - | fallback | `ComponentType`, `VdomDict`, `None` | The `component` or `idom.html` snippet to render if the user is not authenticated. | `None` | + | `auth_attribute` | `str` | The value to check within the user object. This is checked in the form of `UserModel.`. | `#!python "is_active"` | + | `fallback` | `ComponentType`, `VdomDict`, `None` | The `component` or `idom.html` snippet to render if the user is not authenticated. | `None` | **Returns** diff --git a/docs/src/features/hooks.md b/docs/src/features/hooks.md index b35f43ae..ed132b89 100644 --- a/docs/src/features/hooks.md +++ b/docs/src/features/hooks.md @@ -53,21 +53,21 @@ The function you provide into this hook must return either a `Model` or `QuerySe | Name | Type | Description | Default | | --- | --- | --- | --- | - | query | `Callable[_Params, _Result | None]` | A callable that returns a Django `Model` or `QuerySet`. | N/A | - | *args | `_Params.args` | Positional arguments to pass into `query`. | N/A | - | **kwargs | `_Params.kwargs` | Keyword arguments to pass into `query`. | N/A | + | `query` | `Callable[_Params, _Result | None]` | A callable that returns a Django `Model` or `QuerySet`. | N/A | + | `*args` | `_Params.args` | Positional arguments to pass into `query`. | N/A | + | `**kwargs` | `_Params.kwargs` | Keyword arguments to pass into `query`. | N/A | **Returns** | Type | Description | | --- | --- | - | `Query[_Result | None]` | A dataclass containing `loading`/`error` states, your `data` (if the query has successfully executed), and a `refetch` callable that can be used to re-run the query. | + | `Query[_Result | None]` | An object containing `loading`/`error` states, your `data` (if the query has successfully executed), and a `refetch` callable that can be used to re-run the query. | ??? question "Can I make ORM calls without hooks?" Due to Django's ORM design, database queries must be deferred using hooks. Otherwise, you will see a `SynchronousOnlyOperation` exception. - This may be resolved in a future version of Django with a natively asynchronous ORM. + This may be resolved in a future version of Django containing an asynchronous ORM. ??? question "Why does the example `get_items` function return a `Model` or `QuerySet`?" @@ -128,14 +128,14 @@ The function you provide into this hook will have no return value. | Name | Type | Description | Default | | --- | --- | --- | --- | - | mutate | `Callable[_Params, bool | None]` | A callable that performs Django ORM create, update, or delete functionality. If this function returns `False`, then your `refetch` function will not be used. | N/A | - | refetch | `Callable[..., Any] | Sequence[Callable[..., Any]] | None` | A `query` function (used by the `use_query` hook) or a sequence of `query` functions that will be called if the mutation succeeds. This is useful for refetching data after a mutation has been performed. | `None` | + | `mutate` | `Callable[_Params, bool | None]` | A callable that performs Django ORM create, update, or delete functionality. If this function returns `False`, then your `refetch` function will not be used. | N/A | + | `refetch` | `Callable[..., Any] | Sequence[Callable[..., Any]] | None` | A `query` function (used by the `use_query` hook) or a sequence of `query` functions that will be called if the mutation succeeds. This is useful for refetching data after a mutation has been performed. | `None` | **Returns** | Type | Description | | --- | --- | - | `Mutation[_Params]` | A dataclass containing `loading`/`error` states, a `reset` callable that will set `loading`/`error` states to defaults, and a `execute` callable that will run the query. | + | `Mutation[_Params]` | An object containing `loading`/`error` states, a `reset` callable that will set `loading`/`error` states to defaults, and a `execute` callable that will run the query. | ??? question "Can `use_mutation` trigger a refetch of `use_query`?" @@ -240,7 +240,7 @@ The function you provide into this hook will have no return value. Due to Django's ORM design, database queries must be deferred using hooks. Otherwise, you will see a `SynchronousOnlyOperation` exception. - This may be resolved in a future version of Django with a natively asynchronous ORM. + This may be resolved in a future version of Django containing an asynchronous ORM. However, even when resolved it is best practice to perform ORM queries within the `use_query` in order to handle `loading` and `error` states. diff --git a/docs/src/features/settings.md b/docs/src/features/settings.md index c6a7c020..b0dd15c2 100644 --- a/docs/src/features/settings.md +++ b/docs/src/features/settings.md @@ -9,7 +9,7 @@ ```python linenums="1" - # If "idom" cache is not configured, then we'll use "default" instead + # If "idom" cache is not configured, then we will use "default" instead CACHES = { "idom": {"BACKEND": ...}, } diff --git a/docs/src/features/templatetag.md b/docs/src/features/templatetag.md index 3e7731d9..201a6f8c 100644 --- a/docs/src/features/templatetag.md +++ b/docs/src/features/templatetag.md @@ -62,8 +62,8 @@ | Name | Type | Description | Default | | --- | --- | --- | --- | - | dotted_path | `str` | The dotted path to the component to render. | N/A | - | **kwargs | `Any` | The keyword arguments to pass to the component. | N/A | + | `dotted_path` | `str` | The dotted path to the component to render. | N/A | + | `**kwargs` | `Any` | The keyword arguments to pass to the component. | N/A | **Returns** @@ -109,7 +109,7 @@ You can think of template tags as Django's way of allowing you to run Python code within your HTML. Django IDOM uses a `#!jinja {% component ... %}` template tag to perform it's magic. - Keep in mind, in order to use the `#!jinja {% component ... %}` tag, you'll need to first call `#!jinja {% load idom %}` to gain access to it. + Keep in mind, in order to use the `#!jinja {% component ... %}` tag, you will need to first call `#!jinja {% load idom %}` to gain access to it. === "my-template.html" diff --git a/docs/src/getting-started/initial-steps.md b/docs/src/getting-started/initial-steps.md index 98a58d0b..9dac14b8 100644 --- a/docs/src/getting-started/initial-steps.md +++ b/docs/src/getting-started/initial-steps.md @@ -4,15 +4,15 @@ --- -If you've reached this point, you should have already [installed Django-IDOM](../installation/index.md) through the previous steps. +If you have reached this point, you should have already [installed Django-IDOM](../installation/index.md) through the previous steps. -For the examples within this section, we will assume you've placed the files [generated by `startapp`](https://docs.djangoproject.com/en/dev/intro/tutorial01/#creating-the-polls-app) directly into your **Django project** folder. This is common for small projects. +For the examples within this section, we will assume you have placed the files [generated by `startapp`](https://docs.djangoproject.com/en/dev/intro/tutorial01/#creating-the-polls-app) directly into your **Django project** folder. This is common for small projects. ??? question "How do I organize my Django project for IDOM?" Django-IDOM has no project structure requirements. Organize everything as you wish, just like any **Django project**. -??? question "I've never used Django, what do I need to learn?" +??? question "I have never used Django, what do I need to learn?" {% include-markdown "../installation/index.md" start="" end="" %} diff --git a/docs/src/getting-started/learn-more.md b/docs/src/getting-started/learn-more.md index c2d98e1b..b41b6484 100644 --- a/docs/src/getting-started/learn-more.md +++ b/docs/src/getting-started/learn-more.md @@ -1,6 +1,6 @@ # :confetti_ball: Congratulations :confetti_ball: -If you followed the previous steps, you've now created a "Hello World" component! +If you followed the previous steps, you have now created a "Hello World" component! The docs you are reading only covers our Django integration. To learn more about features, such as interactive events and hooks, check out the [IDOM Core Documentation](https://idom-docs.herokuapp.com/docs/guides/creating-interfaces/index.html)! diff --git a/docs/src/getting-started/render-view.md b/docs/src/getting-started/render-view.md index b1055d9b..6319381a 100644 --- a/docs/src/getting-started/render-view.md +++ b/docs/src/getting-started/render-view.md @@ -4,9 +4,9 @@ --- -We will assume you've [created a Django View](https://docs.djangoproject.com/en/dev/intro/tutorial01/#write-your-first-view) before, but here's a simple example below. +We will assume you have [created a Django View](https://docs.djangoproject.com/en/dev/intro/tutorial01/#write-your-first-view) before, but here's a simple example below. -Within your **Django app**'s `views.py` file, you'll need to create a function to render the HTML template containing your IDOM components. +Within your **Django app**'s `views.py` file, you will need to create a function to render the HTML template containing your IDOM components. In this example, we will create a view that renders `my-template.html` (_from the previous step_). diff --git a/docs/src/installation/index.md b/docs/src/installation/index.md index a59816fc..dae49f37 100644 --- a/docs/src/installation/index.md +++ b/docs/src/installation/index.md @@ -8,13 +8,13 @@ pip install django-idom ``` -You'll also need to modify a few files in your **Django project**... +You will also need to modify a few files in your **Django project**... --- ## Configure [`settings.py`](https://docs.djangoproject.com/en/dev/topics/settings/) -In your settings you'll need to add `django_idom` to [`INSTALLED_APPS`](https://docs.djangoproject.com/en/dev/ref/settings/#std:setting-INSTALLED_APPS). +In your settings you will need to add `django_idom` to [`INSTALLED_APPS`](https://docs.djangoproject.com/en/dev/ref/settings/#std:setting-INSTALLED_APPS). === "settings.py" @@ -29,7 +29,7 @@ In your settings you'll need to add `django_idom` to [`INSTALLED_APPS`](https:// Django-IDOM requires ASGI in order to use Websockets. - If you haven't enabled ASGI on your **Django project** yet, you'll need to install `channels[daphne]`, add `daphne` to `INSTALLED_APPS`, then set your `ASGI_APPLICATION` variable. + If you have not enabled ASGI on your **Django project** yet, you will need to install `channels[daphne]`, add `daphne` to `INSTALLED_APPS`, then set your `ASGI_APPLICATION` variable. Read the [Django Channels Docs](https://channels.readthedocs.io/en/stable/installation.html) for more info. @@ -97,6 +97,6 @@ Register IDOM's Websocket using `IDOM_WEBSOCKET_PATH`. ) ``` -??? question "Where is my asgi.py?" +??? question "Where is my `asgi.py`?" If you do not have an `asgi.py`, follow the [`channels` installation guide](https://channels.readthedocs.io/en/stable/installation.html). diff --git a/mkdocs.yml b/mkdocs.yml index c3c339ec..e13a6815 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -65,6 +65,10 @@ plugins: - include-markdown - git-revision-date-localized: fallback_to_build_date: true + - spellcheck: + known_words: dictionary.txt + allow_unicode: no + ignore_code: yes extra: generator: false diff --git a/requirements/build-docs.txt b/requirements/build-docs.txt index 87761d74..fbaebe2d 100644 --- a/requirements/build-docs.txt +++ b/requirements/build-docs.txt @@ -2,4 +2,5 @@ mkdocs mkdocs-git-revision-date-localized-plugin mkdocs-material mkdocs-include-markdown-plugin -linkcheckmd \ No newline at end of file +linkcheckmd +mkdocs-spellcheck