Skip to content

Commit 69c91f6

Browse files
thclarkthclark
committed
DOC: Update and restructure documentation
1 parent 546ae2a commit 69c91f6

File tree

9 files changed

+286
-161
lines changed

9 files changed

+286
-161
lines changed

‎.devcontainer/devcontainer.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -79,7 +79,7 @@
7979
},
8080

8181
// Use 'forwardPorts' to make a list of ports inside the container available locally.
82-
"forwardPorts": [80, 443, 5000, 7045, 7046, 7047, 7048, 7049, 8000, 8080],
82+
"forwardPorts": [80, 443, 5500, 8000],
8383

8484
// Use 'postCreateCommand' to run commands after the container is created.
8585
// Note: Reverting to use pip requirements until we can install private dependencies in GHA with poetry

‎.devcontainer/postcreate.sh‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,5 +3,8 @@
33
# Install dependencies
44
poetry install
55

6+
# Allow precommit to install properly
7+
git config --global --add safe.directory /workspace
8+
69
# Install precommit hooks
710
pre-commit install && pre-commit install -t commit-msg

‎CONTRIBUTING.md‎

Lines changed: 76 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,76 @@
1+
# Contributing
2+
3+
## Where to start
4+
5+
The best place to start is by raising an issue on this repository (or identifying an existing issue and commenting there that you'll be working on it). If you need we can help you get started and sanity-check your approach.
6+
7+
## Developers Getting Started
8+
9+
To get started with developing `django-svelte-jsoneditor`, fork the repo then open an environment in the devcontainer (the easiest way is to use GitHub codespaces or VSCode remote containers), then type:
10+
11+
```
12+
python manage.py migrate
13+
python manage.py createsuperuser
14+
# (then enter user details for yourself)
15+
python manage.py runserver
16+
# (then go to the localhost address in your browser)
17+
# (and in another terminal...)
18+
pytest
19+
# (this should run all tests and have them pass)
20+
```
21+
22+
You'll find this takes you to the django admin where you have several example models registered, each of which use slightly different options on the json field, so you can see how the widget behaves.
23+
24+
### About Svelte
25+
26+
**You don't need to know or care.** It's the JavaScript framework used to develop the widget - but the widget JS is all pre-built so there are no extra requirements.
27+
28+
## Commit messages
29+
30+
We use conventional commits, both to facilitate semantic version checking and to allow automatic generation of PR descriptions and release notes. This means:
31+
32+
- Your commit messages will be part of the release notes. Please keep your commit messages short (<72 characters) and descriptive of the change made in that commit.
33+
34+
- Please use the following [conventional commit codes](https://github.com/octue/conventional-commits#default-allowed-commit-codes)
35+
36+
- Breaking changes should be indicated by starting the body of the commit message with `BREAKING-CHANGE: <explain what users should do to migrate past the change`, eg you'd do:
37+
38+
```
39+
git commit the_file_you_changed.py -m "FEA: New feature to do XYZ
40+
41+
BREAKING-CHANGE: To implement XYZ, we had to remove setting ABC. To update, users should remove setting ABC and replace it with setting PQR"
42+
```
43+
44+
## Pre-Commit
45+
46+
We use [`pre-commit`](https://pre-commit.com/) to apply consistent code quality checks and linting to new code, commit messages, and documentation.
47+
48+
You need to install pre-commit to get the hooks working. Run:
49+
50+
```
51+
pip install pre-commit
52+
pre-commit install && pre-commit install -t commit-msg
53+
```
54+
55+
Once that's done, each time you make a commit, [a range of checks](/.pre-commit-config.yaml) are made.
56+
57+
Upon failure, the commit will halt. **Re-running the commit will automatically fix most issues** except:
58+
59+
- The `flake8` checks... hopefully over time `black` (which fixes most things automatically already) will remove the need for it
60+
- Docstrings - the error messages should explain how to fix these easily
61+
- You'll have to fix documentation yourself prior to a successful commit (there's no auto fix for that!!)
62+
- Commit messages - the error messages should explain how to fix these too
63+
64+
You can run pre-commit hooks without making a commit, too, like:
65+
66+
```
67+
pre-commit run black --all-files
68+
```
69+
70+
## Documentation
71+
72+
If you're unfamiliar with sphinx or reStructuredText, You can build html documentation using:
73+
74+
```
75+
pre-commit run --all-files build-docs -v
76+
```

‎README.md‎

Lines changed: 2 additions & 158 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
[![PyPI version](https://badge.fury.io/py/django-svelte-jsoneditor.svg)](https://badge.fury.io/py/django-svelte-jsoneditor)
2-
[![Documentation Status](https://readthedocs.org/projects/django-svelte-jsoneditor/badge/?version=latest)](https://django-svelte-jsoneditor.readthedocs.io/en/latest/?badge=latest)
2+
[![Documentation Status](https://readthedocs.org/projects/django-svelte-jsoneditor/badge/?version=latest)](https://django-svelte-jsoneditor.readthedocs.io/en/latest/)
33
[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
44
[![pre-commit](https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit&logoColor=white)](https://github.com/pre-commit/pre-commit)
55
[![codeql](https://github.com/octue/django-svelte-jsoneditor/actions/workflows/codeql.yml/badge.svg)](https://github.com/octue/django-svelte-jsoneditor/actions/workflows/codeql.yml)
@@ -8,160 +8,4 @@
88

99
A plug in widget for django's JSONField that allows manipulation and display of JSON data. The widget is built using Jos deJong's new [svelte-jsoneditor](https://github.com/josdejong/svelte-jsoneditor).
1010

11-
This app is a replacement for `django-jsoneditor` (which uses a deprecated version of the widget, `jsoneditor` - you can [see the differences here](https://github.com/josdejong/svelte-jsoneditor#differences-between-josdejongsvelte-jsoneditor-and-josdejongjsoneditor)). You can read about why we're not directly contributing to `django-jsoneditor` [here](https://github.com/nnseva/django-jsoneditor/issues/71), the two projects might merge in the future.
12-
13-
## Documentation
14-
15-
### Installation
16-
17-
To get an application installed in your project, you need to add `django_svelte_jsoneditor` into `INSTALLED_APPS` in `settings.py` file.
18-
19-
```python
20-
# settings.py
21-
22-
INSTALLED_APPS = [
23-
# Other Django applications
24-
"django_svelte_jsoneditor",
25-
]
26-
```
27-
28-
### Usage
29-
30-
The application contains new widget called `SvelteJSONEditorWidget` which adds editor capabilities to JSON fields in Django. Below you can see an example, of how to override the default widget for the JSON field (in this case textarea widget).
31-
32-
```python
33-
# admin.py
34-
35-
from django.contrib import admin
36-
from django_svelte_jsoneditor.widgets import SvelteJSONEditorWidget
37-
38-
from .models import MyModel
39-
40-
41-
@admin.register(MyModel)
42-
class MyModelAdmin(admin.ModelAdmin):
43-
formfield_overrides = {
44-
models.JSONField: {
45-
"widget": SvelteJSONEditorWidget,
46-
}
47-
}
48-
```
49-
50-
Another example is how to create a new Django form integrating `SvelteJSONEditorWidget` replacing `Textarea` widget.
51-
52-
```python
53-
# forms.py
54-
from django import forms
55-
from django_svelte_jsoneditor.widgets import SvelteJSONEditorWidget
56-
57-
58-
class MyJSONEditorForm(forms.Form):
59-
json = forms.JSONField(widgets=SvelteJSONEditorWidget())
60-
```
61-
62-
### Global settings
63-
64-
The application allows modifying some properties of svelte-jsoneditor inside the settings.py configuration file in Django. Official documentation is available on [svelte-jsoneditor](https://github.com/josdejong/svelte-jsoneditor#properties) GitHub page. **Note:** Not all options are configurable which are provided by svelte-jsoneditor.
65-
66-
```python
67-
# settings.py
68-
69-
SVELTE_JSONEDITOR_PROPS = {
70-
"mode": "tree",
71-
"mainMenuBar": True,
72-
"navigationBar": True,
73-
"statusBar": True,
74-
"askToFormat": True,
75-
"readOnly": False,
76-
"indentation": 4,
77-
"tabSize": 4,
78-
"escapeControlCharacters": False,
79-
"escapeUnicodeCharacters": False,
80-
"flattenColumns": True,
81-
}
82-
```
83-
84-
#### Available properties
85-
86-
| Property | Type | Default |
87-
| ----------------------- | --------------------------- | ------- |
88-
| mode | 'tree' or 'text' or 'table' | 'tree' |
89-
| mainMenuBar | boolean | True |
90-
| navigationBar | boolean | True |
91-
| statusBar | boolean | True |
92-
| askToFormat | boolean | True |
93-
| readOnly | boolean | False |
94-
| indentation | number or string | 4 |
95-
| tabSize | number | 4 |
96-
| escapeControlCharacters | boolean | False |
97-
| escapeUnicodeCharacters | boolean | False |
98-
| flattenColumns | boolean | True |
99-
100-
### Widget properties
101-
102-
`SvelteJSONEditorWidget` has additional argument called `props` which allows to override `SVELTE_JSONEDITOR` settings from settings.py.
103-
104-
```python
105-
# forms.py
106-
107-
from django import forms
108-
109-
110-
class SvelteJsonEditorForm(forms.Form):
111-
my_json = forms.JSONField(widget=SvelteJSONEditorWidget(props={
112-
"readOnly": True
113-
}))
114-
```
115-
116-
#### Custom widget properties in admin form
117-
118-
```python
119-
# admin.py
120-
121-
from django import forms
122-
from django.contrib import admin
123-
124-
from .models import ExampleModel
125-
126-
class CustomForm(forms.ModelForm):
127-
class Meta:
128-
model = ExampleModel
129-
fields = "__all__"
130-
131-
def __init__(self, *args, **kwargs):
132-
super().__init__(*args, **kwargs)
133-
self.fields["some_json_field"].widget = SvelteJSONEditorWidget(props={"readOnly": True})
134-
135-
136-
@admin.register(ExampleModel, ExampleModelAdmin)
137-
class ExampleModelAdmin(admin.ModelAdmin):
138-
form = CustomForm
139-
formfield_overrides = {
140-
models.JSONField: {
141-
"widget": SvelteJSONEditorWidget,
142-
}
143-
}
144-
```
145-
146-
## About Svelte
147-
148-
**You don't need to know or care.** It's the JavaScript framework used to develop the widget - but the widget JS is all pre-built so there are no extra requirements.
149-
150-
### Developing
151-
152-
To get started with developing `django-svelte-jsoneditor`, fork the repo then open an environment in the devcontainer (the easiest way is to use GitHub codespaces or VSCode remote containers), then type:
153-
154-
```
155-
python manage.py migrate
156-
python manage.py createsuperuser
157-
# (then enter user details for yourself)
158-
python manage.py runserver
159-
# (then go to the localhost address in your browser)
160-
# (and in another terminal...)
161-
pytest
162-
# (this should run all tests and have them pass)
163-
```
164-
165-
You'll find this takes you to the django admin where you have several example models registered, each of which use slightly different options on the json field, so you can see how the widget behaves.
166-
167-
**On the subject of commit messages**. It's helpful if you use the following [conventional commit codes](https://github.com/octue/conventional-commits#default-allowed-commit-codes) because then the PR and release notes get generated automatically!
11+
[**Read the documentation here.**](https://django-svelte-jsoneditor.readthedocs.io/en/latest/)

‎docs/source/contributing.rst‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
.. _contributing:
2+
3+
============
4+
Contributing
5+
============
6+
7+
If you'd like to contribute to ``django_svelte_jsoneditor``, you'll be most welcome! Please `start by reading our contributing guidelines `<https://github.com/octue/django-svelte-jsoneditor/blob/main/CONTRIBUTING.md>`_.

‎docs/source/editor_properties.rst‎

Lines changed: 111 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,111 @@
1+
2+
.. _editor_properties:
3+
4+
=================
5+
Editor Properties
6+
=================
7+
8+
The ``svelte-jsoneditor`` has a range of properties allowing customisation of appearance and function. The ``SvelteJSONEditorWidget`` allows you to alter ``svelte-jsoneditor``'s defaults.
9+
10+
.. ATTENTION::
11+
Not all ``svelte-jsoneditor`` properties are configurable, notably the ``on*`` callbacks. To add such callbacks you'd need to override the widget template yourself, since they require javascript functions.
12+
13+
14+
.. _available_properties:
15+
16+
Available Properties
17+
====================
18+
19+
Official documentation and descriptions are available on `the svelte-jsoneditor GitHub page <https://github.com/josdejong/svelte-jsoneditor#properties>`_.
20+
21+
========================= ============================= =========
22+
Property Type Default
23+
========================= ============================= =========
24+
mode 'tree' or 'text' or 'table' 'tree'
25+
mainMenuBar boolean True
26+
navigationBar boolean True
27+
statusBar boolean True
28+
askToFormat boolean True
29+
readOnly boolean False
30+
indentation number or string 4
31+
tabSize number 4
32+
escapeControlCharacters boolean False
33+
escapeUnicodeCharacters boolean False
34+
flattenColumns boolean True
35+
========================= ============================= =========
36+
37+
38+
.. _using_properties:
39+
40+
Using Properties
41+
================
42+
43+
To alter the default properties used by ALL widgets in your application, see the :ref:`SVELTE_JSONEDITOR_PROPS <svelte_jsoneditor_props>` setting.
44+
45+
To alter the widget for an individual field, the ``SvelteJSONEditorWidget`` accepts an additional argument, ``props``. The following example shows this used in a form:
46+
47+
.. code-block:: py
48+
49+
# forms.py
50+
51+
from django import forms
52+
53+
54+
class SvelteJsonEditorForm(forms.Form):
55+
my_json = forms.JSONField(widget=SvelteJSONEditorWidget(props={
56+
"readOnly": True
57+
}))
58+
59+
60+
Or to use custom widget properties in the django admin:
61+
62+
.. code-block:: py
63+
64+
# admin.py
65+
66+
from django import forms
67+
from django.contrib import admin
68+
69+
from .models import ExampleModel
70+
71+
class CustomForm(forms.ModelForm):
72+
class Meta:
73+
model = ExampleModel
74+
fields = "__all__"
75+
76+
def __init__(self, *args, **kwargs):
77+
super().__init__(*args, **kwargs)
78+
self.fields["some_json_field"].widget = SvelteJSONEditorWidget(props={"readOnly": True})
79+
80+
81+
@admin.register(ExampleModel, ExampleModelAdmin)
82+
class ExampleModelAdmin(admin.ModelAdmin):
83+
form = CustomForm
84+
formfield_overrides = {
85+
models.JSONField: {
86+
"widget": SvelteJSONEditorWidget,
87+
}
88+
}
89+
90+
91+
92+
93+
94+
95+
96+
.. # settings.py
97+
98+
.. SVELTE_JSONEDITOR_PROPS = {
99+
.. "mode": "tree",
100+
.. "mainMenuBar": True,
101+
.. "navigationBar": True,
102+
.. "statusBar": True,
103+
.. "askToFormat": True,
104+
.. "readOnly": False,
105+
.. "indentation": 4,
106+
.. "tabSize": 4,
107+
.. "escapeControlCharacters": False,
108+
.. "escapeUnicodeCharacters": False,
109+
.. "flattenColumns": True,
110+
.. }
111+
.. ```

0 commit comments

Comments
 (0)