From 16652b7c2f0d87025f9f4c4edf2c1f33d50eed06 Mon Sep 17 00:00:00 2001 From: Archmonger <16909269+Archmonger@users.noreply.github.com> Date: Tue, 6 Jun 2023 00:00:11 -0700 Subject: [PATCH] Docs and readme tweaks --- CHANGELOG.md | 2 +- README.md | 29 ++++++++++++++++++----- docs/src/changelog/index.md | 2 -- docs/src/contribute/code.md | 4 +--- docs/src/contribute/docs.md | 4 +--- docs/src/contribute/running-tests.md | 4 +--- docs/src/features/components.md | 4 +--- docs/src/features/decorators.md | 4 +--- docs/src/features/hooks.md | 6 ++--- docs/src/features/settings.md | 4 +--- docs/src/features/template-tag.md | 4 +--- docs/src/features/utils.md | 4 +--- docs/src/get-started/choose-django-app.md | 4 +--- docs/src/get-started/create-component.md | 4 +--- docs/src/get-started/installation.md | 4 +--- docs/src/get-started/learn-more.md | 2 +- docs/src/get-started/register-view.md | 4 +--- docs/src/get-started/run-webserver.md | 4 +--- docs/src/get-started/use-template-tag.md | 4 +--- docs/src/stylesheets/extra.css | 19 +++++++++++---- mkdocs.yml | 5 ++-- 21 files changed, 58 insertions(+), 63 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 55a8c0f5..4587311e 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -203,7 +203,7 @@ Using the following categories, list your changes in this order: ### Added -- Django-specific hooks! `use_websocket`, `use_scope`, and `use_location` are now available within the `django_idom.hooks` module. +- Django specific hooks! `use_websocket`, `use_scope`, and `use_location` are now available within the `django_idom.hooks` module. - Documentation has been placed into a formal docs webpage. - Logging for when a component fails to import, or if no components were found within Django. diff --git a/README.md b/README.md index 90ec4754..f2d0f592 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,23 @@ -[![Tests](https://github.com/reactive-python/reactpy-django/workflows/Test/badge.svg?event=push)](https://github.com/reactive-python/reactpy-django/actions?query=workflow%3ATest) [![PyPI Version](https://img.shields.io/pypi/v/reactpy-django.svg?label=PyPI)](https://pypi.python.org/pypi/reactpy-django) [![License](https://img.shields.io/badge/License-MIT-purple.svg)](https://github.com/reactive-python/reactpy-django/blob/main/LICENSE) [![Docs](https://img.shields.io/website?down_message=offline&label=Docs&logo=read%20the%20docs&logoColor=white&up_message=online&url=https%3A%2F%2Freactive-python.github.io%2Freactpy-django%2F)](https://reactive-python.github.io/reactpy-django/) +

+ + + + + + + + + + + + + + + +

@@ -86,10 +102,11 @@ Additionally, you can pass in `args` and `kwargs` into your component function. Follow the links below to find out more about this project. -- [Try it Now](https://mybinder.org/v2/gh/reactive-python/reactpy-jupyter/main?urlpath=lab/tree/notebooks/introduction.ipynb) - check out ReactPy in a Jupyter Notebook. -- [Documentation](https://reactive-python.github.io/reactpy-django) - learn how to install, run, and use ReactPy. -- [Community Forum](https://github.com/reactive-python/reactpy/discussions) - ask questions, share ideas, and show off projects. -- [Contributor Guide](https://reactive-python.github.io/reactpy-django/contribute/code/) - see how you can help develop this project. -- [Code of Conduct](https://github.com/reactive-python/reactpy-django/blob/main/CODE_OF_CONDUCT.md) - standards for interacting with this community. +- [Try ReactPy (Jupyter Notebook)](https://mybinder.org/v2/gh/reactive-python/reactpy-jupyter/main?urlpath=lab/tree/notebooks/introduction.ipynb) +- [Documentation](https://reactive-python.github.io/reactpy-django) +- [GitHub Discussions](https://github.com/reactive-python/reactpy-django/discussions) +- [Discord](https://discord.gg/uNb5P4hA9X) +- [Contributor Guide](https://reactive-python.github.io/reactpy-django/contribute/code/) +- [Code of Conduct](https://github.com/reactive-python/reactpy-django/blob/main/CODE_OF_CONDUCT.md) diff --git a/docs/src/changelog/index.md b/docs/src/changelog/index.md index 20120d5e..9c2bef97 100644 --- a/docs/src/changelog/index.md +++ b/docs/src/changelog/index.md @@ -7,6 +7,4 @@ hide: {% include-markdown "../../../CHANGELOG.md" start="" end="" %} ---- - {% include-markdown "../../../CHANGELOG.md" start="" %} diff --git a/docs/src/contribute/code.md b/docs/src/contribute/code.md index 05cf0ca6..07824927 100644 --- a/docs/src/contribute/code.md +++ b/docs/src/contribute/code.md @@ -1,6 +1,6 @@ ## Overview -!!! summary +!!! summary "Overview" You will need to set up a Python environment to develop ReactPy-Django. @@ -8,8 +8,6 @@ Everything within the `reactpy-django` repository must be specific to Django integration. Check out the [ReactPy Core documentation](https://reactpy.dev/docs/about/contributor-guide.html) to contribute general features such as: components, hooks, events, and more. ---- - ## Modifying Code If you plan to make code changes to this repository, you will need to install the following dependencies first: diff --git a/docs/src/contribute/docs.md b/docs/src/contribute/docs.md index 549ac780..d5a02be7 100644 --- a/docs/src/contribute/docs.md +++ b/docs/src/contribute/docs.md @@ -1,11 +1,9 @@ ## Overview -!!! summary +!!! summary "Overview" You will need to set up a Python environment to preview docs changes. ---- - ## Modifying Docs If you plan to make changes to this documentation, you will need to install the following dependencies first: diff --git a/docs/src/contribute/running-tests.md b/docs/src/contribute/running-tests.md index 6034253f..b714c5cd 100644 --- a/docs/src/contribute/running-tests.md +++ b/docs/src/contribute/running-tests.md @@ -1,11 +1,9 @@ ## Overview -!!! summary +!!! summary "Overview" You will need to set up a Python environment to run out test suite. ---- - ## Running Tests This repository uses [Nox](https://nox.thea.codes/en/stable/) to run tests. For a full test of available scripts run `nox -l`. diff --git a/docs/src/features/components.md b/docs/src/features/components.md index bf33af2e..d7926803 100644 --- a/docs/src/features/components.md +++ b/docs/src/features/components.md @@ -1,11 +1,9 @@ ## Overview -!!! summary +!!! summary "Overview" Prefabricated components can be used within your `components.py` to help simplify development. ---- - ## View To Component Convert any Django view into a ReactPy 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. diff --git a/docs/src/features/decorators.md b/docs/src/features/decorators.md index ed2b8d09..95779fae 100644 --- a/docs/src/features/decorators.md +++ b/docs/src/features/decorators.md @@ -1,11 +1,9 @@ ## Overview -!!! summary +!!! summary "Overview" Decorator utilities can be used within your `components.py` to help simplify development. ---- - ## Auth Required You can limit access to a component to users with a specific `auth_attribute` by using this decorator (with or without parentheses). diff --git a/docs/src/features/hooks.md b/docs/src/features/hooks.md index dd53ac61..5916776a 100644 --- a/docs/src/features/hooks.md +++ b/docs/src/features/hooks.md @@ -1,17 +1,15 @@ ## Overview -!!! summary +!!! summary "Overview" Prefabricated hooks can be used within your `components.py` to help simplify development. ??? tip "Looking for standard React hooks?" - Standard hooks are contained within [`reactive-python/reactpy`](https://github.com/reactive-python/reactpy). Since `reactpy` is installed alongside `reactpy-django`, you can import them at any time. + The `reactpy-django` package only contains django specific hooks. Standard hooks can be found within [`reactive-python/reactpy`](https://github.com/reactive-python/reactpy). Since `reactpy` is installed alongside `reactpy-django`, you can import them at any time. Check out the [ReactPy Core docs](https://reactpy.dev/docs/reference/hooks-api.html#basic-hooks) to see what hooks are available! ---- - ## Use Query The `use_query` hook is used fetch Django ORM queries. diff --git a/docs/src/features/settings.md b/docs/src/features/settings.md index 1454f6aa..3abd6575 100644 --- a/docs/src/features/settings.md +++ b/docs/src/features/settings.md @@ -1,11 +1,9 @@ ## Overview -!!! summary +!!! summary "Overview" Your **Django project's** `settings.py` can modify the behavior of ReactPy. ---- - ## Primary Configuration These are ReactPy-Django's default settings values. You can modify these values in your **Django project's** `settings.py` to change the behavior of ReactPy. diff --git a/docs/src/features/template-tag.md b/docs/src/features/template-tag.md index 266b75ec..9d4ca18c 100644 --- a/docs/src/features/template-tag.md +++ b/docs/src/features/template-tag.md @@ -1,11 +1,9 @@ ## Overview -!!! summary +!!! summary "Overview" Template tags can be used within your Django templates such as `my-template.html` to import ReactPy features. ---- - ## Component The `component` template tag can be used to insert any number of ReactPy components onto your page. diff --git a/docs/src/features/utils.md b/docs/src/features/utils.md index 73c5248d..9cec1aa4 100644 --- a/docs/src/features/utils.md +++ b/docs/src/features/utils.md @@ -1,11 +1,9 @@ ## Overview -!!! summary +!!! summary "Overview" Utility functions that you can use when needed. ---- - ## Django Query Postprocessor This is the default postprocessor for the `use_query` hook. diff --git a/docs/src/get-started/choose-django-app.md b/docs/src/get-started/choose-django-app.md index 5f83fc2a..61dcfdba 100644 --- a/docs/src/get-started/choose-django-app.md +++ b/docs/src/get-started/choose-django-app.md @@ -1,11 +1,9 @@ ## Overview -!!! summary +!!! summary "Overview" Set up a **Django Project** with at least one app. ---- - ## Choose a Django App If you have reached this point, you should have already [installed ReactPy-Django](../get-started/installation.md) through the previous steps. diff --git a/docs/src/get-started/create-component.md b/docs/src/get-started/create-component.md index e0516002..032906e7 100644 --- a/docs/src/get-started/create-component.md +++ b/docs/src/get-started/create-component.md @@ -1,11 +1,9 @@ ## Overview -!!! summary +!!! summary "Overview" Create a component function using our decorator. ---- - ## Create a Component {% include-markdown "../../../README.md" start="" end="" %} diff --git a/docs/src/get-started/installation.md b/docs/src/get-started/installation.md index a27a3dc7..21e26201 100644 --- a/docs/src/get-started/installation.md +++ b/docs/src/get-started/installation.md @@ -1,11 +1,9 @@ ## Overview -!!! summary +!!! summary "Overview" ReactPy-Django can be installed from PyPI to an existing **Django project** with minimal configuration. ---- - ## Step 0: Create a Django Project These docs assumes you have already created [a **Django project**](https://docs.djangoproject.com/en/dev/intro/tutorial01/), which involves creating and installing at least one **Django app**. If not, check out this [9 minute YouTube tutorial](https://www.youtube.com/watch?v=ZsJRXS_vrw0) created by _IDG TECHtalk_. diff --git a/docs/src/get-started/learn-more.md b/docs/src/get-started/learn-more.md index f2cb52ae..8b58400d 100644 --- a/docs/src/get-started/learn-more.md +++ b/docs/src/get-started/learn-more.md @@ -8,4 +8,4 @@ Additionally, the vast majority of tutorials/guides you find for ReactJS can be === "Learn More" - [ReactPy-Django Advanced Usage](../features/components.md){ .md-button .md-button--primary} [ReactPy Core Documentation](https://reactpy.dev/docs/guides/creating-interfaces/index.html){ .md-button .md-button--primary } [Ask Questions](https://github.com/reactive-python/reactpy/discussions){ .md-button .md-button--primary } + [ReactPy-Django Advanced Usage](../features/components.md){ .md-button .md-button--primary} [ReactPy Core Documentation](https://reactpy.dev/docs/guides/creating-interfaces/index.html){ .md-button .md-button--primary } [Ask Questions on Discord](https://discord.gg/uNb5P4hA9X){ .md-button .md-button--primary } diff --git a/docs/src/get-started/register-view.md b/docs/src/get-started/register-view.md index 1c97d089..7f21bd66 100644 --- a/docs/src/get-started/register-view.md +++ b/docs/src/get-started/register-view.md @@ -1,11 +1,9 @@ ## Overview -!!! summary +!!! summary "Overview" Select your template containing an ReactPy component, and render it using a Django view. ---- - ## Register a View 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. diff --git a/docs/src/get-started/run-webserver.md b/docs/src/get-started/run-webserver.md index 1c532558..5a1d27dd 100644 --- a/docs/src/get-started/run-webserver.md +++ b/docs/src/get-started/run-webserver.md @@ -1,11 +1,9 @@ ## Overview -!!! summary +!!! summary "Overview" Run a webserver to display your Django view. ---- - ## Run the Webserver To test your new Django view, run the following command to start up a development webserver. diff --git a/docs/src/get-started/use-template-tag.md b/docs/src/get-started/use-template-tag.md index 6fd9017c..e108e407 100644 --- a/docs/src/get-started/use-template-tag.md +++ b/docs/src/get-started/use-template-tag.md @@ -1,11 +1,9 @@ ## Overview -!!! summary +!!! summary "Overview" Decide where the component will be displayed by using our template tag. ---- - ## Use the Template Tag {% include-markdown "../../../README.md" start="" end="" %} diff --git a/docs/src/stylesheets/extra.css b/docs/src/stylesheets/extra.css index 72e8bd26..1599d525 100644 --- a/docs/src/stylesheets/extra.css +++ b/docs/src/stylesheets/extra.css @@ -31,11 +31,6 @@ border-color: transparent !important; } -[data-md-color-scheme="slate"] .md-typeset .admonition.summary, -[data-md-color-scheme="slate"] .md-typeset details.summary { - background: #353a45; -} - [data-md-color-scheme="slate"] .md-typeset details > .admonition-title:after, [data-md-color-scheme="slate"] .md-typeset details > summary:after { color: var(--md-admonition-fg-color) !important; @@ -45,6 +40,8 @@ [data-md-color-scheme="slate"] .md-typeset .admonition.summary, [data-md-color-scheme="slate"] .md-typeset details.summary { background: #353a45; + padding: 0.8rem 1.4rem; + border-radius: 0.8rem; } [data-md-color-scheme="slate"] .md-typeset details.summary > .admonition-title, @@ -54,7 +51,19 @@ [data-md-color-scheme="slate"] .md-typeset .summary .admonition-title, [data-md-color-scheme="slate"] .md-typeset .summary summary { + font-size: 1rem; background: transparent; + padding-left: 0.6rem; + padding-bottom: 0; +} + +[data-md-color-scheme="slate"] .md-typeset .summary .admonition-title:before { + display: none; +} + +[data-md-color-scheme="slate"] .md-typeset .admonition, +[data-md-color-scheme="slate"] .md-typeset details { + border-color: #ffffff17 !important; } /* Move the sidebars to the edges of the page */ diff --git a/mkdocs.yml b/mkdocs.yml index bca3df26..fa7b5f90 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -21,7 +21,8 @@ nav: - Code: contribute/code.md - Docs: contribute/docs.md - Running Tests: contribute/running-tests.md - - Community: https://github.com/reactive-python/reactpy/discussions + - GitHub Discussions: https://github.com/reactive-python/reactpy-django/discussions + - Discord: https://discord.gg/uNb5P4hA9X - Changelog: changelog/index.md theme: @@ -96,7 +97,7 @@ watch: site_name: ReactPy-Django Docs site_author: Archmonger site_description: React for Django developers. -copyright: Copyright © 2022 Reactive Python +copyright: Copyright © 2023 Reactive Python repo_url: https://github.com/reactive-python/reactpy-django site_url: https://reactive-python.github.io/reactpy-django repo_name: reactive-python/reactpy-django