Docs site for inertia-django adapter #67
Conversation
There was a problem hiding this comment.
Thank you, this is amazing @SarthakJariwala !!
I'm out of town right now, but I'll get this merged and start filling in some of the "coming soon" sections this weekend!
|
Since you have it marked as a draft, are there parts you think we need before merging or is that just because the docs aren't totally complete? |
Since initial setup and configuration has been a pain point for new users, I wanted to make sure that "Server side setup" section was complete before merging. I'll try to fill it out soon. There is also another question of where we host the docs. Would we be able to host it under inertiajs GitHub org or should we get a new domain like inertia-rails did? ( |
- template based setup - manual setup
| ::: tip | ||
| For new projects, we recommend following the [template based setup](#template-based-setup) guide. | ||
| ::: | ||
|
|
||
| ## Template-based setup | ||
|
|
||
| If you're starting a new project, we recommend configuring Django and Inertia using a `django-vite-inertia` template. | ||
|
|
||
| This will require [uv](https://docs.astral.sh/uv/) or [pipx](https://pipx.pypa.io/stable/) to be installed. | ||
|
|
||
| First, let's create a new directory for our project. | ||
|
|
||
| ```shell | ||
| mkdir myproject | ||
| ``` | ||
| Next, we'll use the template based installer. | ||
|
|
||
| ::: code-group | ||
|
|
||
| ```shell [uv] | ||
| uvx copier copy gh:sarthakjariwala/django-vite-inertia myproject | ||
| ``` | ||
|
|
||
| ```shell [pipx] | ||
| pipx run copier copy gh:sarthakjariwala/django-vite-inertia myproject | ||
|
|
||
| ``` | ||
|
|
||
| ::: |
There was a problem hiding this comment.
I thought it would be a good idea to have a template based installation method (similar to inertia-rails). But, if you're not comfortable recommending this approach, I'm ok removing it.
I also have a simpler template based new project setup in another project I'm developing: https://github.com/SarthakJariwala/lfp
In that case, the command would be simpler: uvx lfp new
uvx lfp new uses the currently linked template (gh:sarthakjariwala/django-vite-inertia) under the hood.
From my point of view, either approach would be ok to include, but I do think template based approach is an easier onboarding process compared to manual configuration.
There was a problem hiding this comment.
I think it's awesome that you've taken the initiative to set up starter projects! I just want to make sure I understand the setup (a colleague of mine has been encouraging me to switch to uv, but I'm still stuck on poetry).
At a glance, your template works great. My big question relative to other potential starter kits is does your template have a way to keep up with inertia-django tags or is it downstream of them?
There was a problem hiding this comment.
Thanks! uv definitely feels like the missing piece to python installation and dependency management :-)
The starter project provides only scaffolding - which includes, in my opinion, the most challenging aspect, frontend configuration - integrating Vue, React, or Svelte with django-vite and vite.config.js and inertia.js. The other advantage is also that you get a Dockerfile that you can use for production deployments (if you want one)
The scaffold doesn't utilize any specific features from inertia-django, aside from a basic render call to display the home page and share command in middleware. Therefore, I don't anticipate major issues with maintaining compatibility with future releases of inertia-django.
In the template, the version of inertia-django is specified in the pyproject.toml file to be >=0.6.0, with inertia-django specific configurations located in settings.py. This means that when someone initiates a new project later, they can still utilize this starter template, which will have inertia-django>=0.6.0 in pyproject.toml. Using their preferred dependency resolver (uv or pip), they can install the necessary dependencies, and the resolver will fetch the latest compatible version of inertia-django.
Unless there are specific changes in how inertia-django handles settings or if the render method undergoes a name change, no updates to the inertia-django portion of the template will be required.
The projects that will need closer monitoring are django-vite and inertia.js, as these are more likely to undergo updates impacting the integration. An example would be django-vite changes how it defines dev server settings. In this case, though, docs will also need to be updated - so I don't see it as a major downside.
Let me know if I didn't address your concerns.
I do want to mention that we can also just only mention the manual configuration in the docs as the "official" recommendation and remove template based installation. I do understand that you may not want to pick one solution over the others (yet).
I'm also happy to brainstorm and think of a solution that can be integrated into inertia-django the same way inertia-rails has a bin/rails generate inertia:install command that is first party.
|
|
||
| const title = "Inertia Django"; | ||
| const description = "Build single page apps, without building an API"; | ||
| const site = "https://inertiajs.com"; |
There was a problem hiding this comment.
Related to my comment from earlier: I'm not sure what this should be. I guess it depends on where we decide to host the docs.
There was a problem hiding this comment.
I'm double checking right now with some of our users, I'll answer here asap. Thank you for checking!
PR adds initial documentation scaffold and setup guides.
Attempts to address #58
To test locally:
cd docs && npm i && npm run docs:devnpm run docs:build && npm run docs:preview