v1.0.0

[Archmonger]

Changelog

• Change Django IDOM version to 1.0.0
• Unpins top boundary on channels and aiofile
• Bumps IDOM's minimum version
• Use f-strings when possible
• Use contexlib.suppress when possible
• Implement use_websocket, use_scope, and use_location
• Remove websocket parameter from components (replaced by use_websocket hook)
• Create formal docs
• Rename idom_component template tag to component in preparation for repo rename (reactive)
• Logging for when a component fails to import, or if no components were found within Django.

Docs Preview

1. pip install -U -r requirements/build-docs.txt
2. mkdocs serve

[Archmonger]

@rmorshea What's the new replacement for dispatch_single_view?

[rmorshea]

idom.core.serve.serve_json_patch

[Archmonger]

Wait - I should probably implement all the hooks (ex use_scope) for Django IDOM in this PR...

[Archmonger]

This PR is feature complete.

Only one question remains... Do we awkwardly document the new hooks within the readme, or should I start generating some django_idom docs as a part of this PR?

[Archmonger]

@rmorshea if I use this PR to create docs, my preferred docs deployment is via mkdocs, hosted via github pages.

Let me know if this is alright with you.

[rmorshea]

Go for it! I'm fine with mkdocs, plus md is better than rst for most people.

[Archmonger]

New docs are up. Still need some final touches though.

If you want to test them later:

1. pip install requirements/build-docs.txt
2. mkdocs serve

I'm thinking this PR should also pre-emptively rename the idom_component template tag to component. When the repo rename comes around, reactive_component feels like a bit too long of a string.

[rmorshea]

Looked at the changelog entry and the described changes LGTM. Will take a look at the rest in more detail once back.

[Archmonger]

When you review, if you like the style of documentation I generated for DJ-idom then I'd like to replicate it to IDOM core.

[Archmonger]

@rmorshea Do you have availability to review this week?

[rmorshea]

I should

[rmorshea]

I looked through all the code and most of the docs. They all look great! I don't have my personal computer with me at the moment so I won't be able to see what the rendered website looks like till next week. If you want you could email me a zip of the build, but I think this LGTM. Any minor things that need to be improved in the docs could be done in a separate PR.

[Archmonger]

django-idom_docs_5-27-2022.zip

@rmorshea mkdocs builds are slim enough to fit into github attachments, so I've attached it to this comment.

[rmorshea]

Will take a look tomorrow.

[rmorshea]

LGTM!

[Archmonger]

@rmorshea The docs are now live at https://idom-team.github.io/django-idom/

On that note... This is my preferred layout for docs due to readability. If you like it, I can draft a PR for IDOM Core to migrate to this same format. In terms of section names and information layout, I believe the ReactJS beta docs are bad. Ironically, I think the non-beta docs are pretty solid.

Also, markdown makes it a lot easier for new users to contribute docs changes. Keeping the bar to entry low is pretty important.

[rmorshea]

I think the "Getting Started" section of the core documentation could definitely use improvements to organization and content. I think the content in the remaining "guides" are pretty solid. I'd be open to improving organization but I'm hesitant to spend a lot of time changing content without feedback from readers of it. I'm less opinionated about the rest (e.g. "Reference" and "About" sections.

With respect to markdown, I tried getting the docs to work with Myst, but I took a lot of shortcuts with the Sphinx extensions that enable the interactive examples. As a result, things broke when I added Myst. Specifically, I resorted to using ReST templates instead of actually figuring out how to use directives within my extension.

[Archmonger]

Markdown supports embedding raw HTML. Wouldn't that suffice, if we were to switch to mkdocs?

Also in terms of other things we'd need to replicate...
Macros: https://github.com/fralau/mkdocs_macros_plugin
Automatic code documentation: https://mkdocstrings.github.io/
Interactive examples: https://github.com/danielfrg/mkdocs-jupyter or https://github.com/greenape/mknotebooks

[rmorshea]

I'd prefer to stick with the docs tooling we have for now. I don't think having the documentation written in Markdown provides enough of a benefit vs the time it will cost of making the changes. With that said, Myst seems like an attractive option for switching to Markdown because it can be integrated progressively.

[Archmonger]

By the way, what do you think about the grey/orange color scheme?