You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: README.md
+2Lines changed: 2 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -65,6 +65,8 @@ As **SQLModel** is based on **Pydantic** and **SQLAlchemy**, it requires them. T
65
65
66
66
## Installation
67
67
68
+
Make sure you create a <ahref="https://sqlmodel.tiangolo.com/virtual-environments/"class="external-link"target="_blank">virtual environment</a>, activate it, and then install SQLModel, for example with:
Copy file name to clipboardExpand all lines: docs/contributing.md
+87-47Lines changed: 87 additions & 47 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -4,49 +4,43 @@ First, you might want to see the basic ways to [help SQLModel and get help](help
4
4
5
5
## Developing
6
6
7
-
If you already cloned the repository and you know that you need to deep dive in the code, here are some guidelines to set up your environment.
7
+
If you already cloned the <ahref="https://github.com/fastapi/sqlmodel"class="external-link"target="_blank">sqlmodel repository</a> and you want to deep dive in the code, here are some guidelines to set up your environment.
8
8
9
-
### Poetry
9
+
### Virtual Environment
10
10
11
-
**SQLModel** uses <ahref="https://python-poetry.org/"class="external-link"target="_blank">Poetry</a> to build, package, and publish the project.
11
+
Follow the instructions to create and activate a [virtual environment](virtual-environments.md){.internal-link target=_blank} for the internal code of `sqlmodel`.
12
12
13
-
You can learn how to install it in the <ahref="https://python-poetry.org/docs/#installation"class="external-link"target="_blank">Poetry docs</a>.
13
+
### Install Requirements Using `pip`
14
14
15
-
After having Poetry available, you can install the development dependencies:
15
+
After activating the environment, install the required packages:
16
16
17
17
<divclass="termy">
18
18
19
19
```console
20
-
$ poetry install
20
+
$ pip install -r requirements.txt
21
21
22
22
---> 100%
23
23
```
24
24
25
25
</div>
26
26
27
-
It will also create a virtual environment automatically and will install all the dependencies and your local SQLModel in it.
27
+
It will install all the dependencies and your local SQLModel in your local environment.
28
28
29
-
### Poetry Shell
29
+
### Using your Local SQLModel
30
30
31
-
To use your current environment, and to have access to all the tools in it (for example `pytest` for the tests) enter into a Poetry Shell:
31
+
If you create a Python file that imports and uses SQLModel, and run it with the Python from your local environment, it will use your cloned local SQLModel source code.
32
32
33
-
<divclass="termy">
34
-
35
-
```console
36
-
$ poetry shell
37
-
```
33
+
And if you update that local SQLModel source code when you run that Python file again, it will use the fresh version of SQLModel you just edited.
38
34
39
-
</div>
40
-
41
-
That will set up the environment variables needed and start a new shell with them.
35
+
That way, you don't have to "install" your local version to be able to test every change.
42
36
43
-
#### Using your local SQLModel
37
+
/// note | "Technical Details"
44
38
45
-
If you create a Python file that imports and uses SQLModel, and run it with the Python from your local Poetry environment, it will use your local SQLModel source code.
39
+
This only happens when you install using this included `requirements.txt` instead of running `pip install sqlmodel` directly.
46
40
47
-
And if you update that local SQLModel source code, when you run that Python file again, it will use the fresh version of SQLModel you just edited.
41
+
That is because inside the `requirements.txt` file, the local version of SQLModel is marked to be installed in "editable" mode, with the `-e` option.
48
42
49
-
Poetry takes care of making that work. But of course, it will only work in the current Poetry environment, if you install standard SQLModel in another environment (not from the source in the GitHub repo), that will use the standard SQLModel, not your custom version.
43
+
///
50
44
51
45
### Format
52
46
@@ -62,41 +56,36 @@ $ bash scripts/format.sh
62
56
63
57
It will also auto-sort all your imports.
64
58
65
-
## Docs
66
-
67
-
The documentation uses <ahref="https://www.mkdocs.org/"class="external-link"target="_blank">MkDocs</a> with <ahref="https://squidfunk.github.io/mkdocs-material/"class="external-link"target="_blank">Material for MkDocs</a>.
68
-
69
-
All the documentation is in Markdown format in the directory `./docs`.
59
+
## Tests
70
60
71
-
Many of the tutorials have blocks of code.
61
+
There is a script that you can run locally to test all the code and generate coverage reports in HTML:
72
62
73
-
In most of the cases, these blocks of code are actual complete applications that can be run as is.
63
+
<divclass="termy">
74
64
75
-
In fact, those blocks of code are not written inside the Markdown, they are Python files in the `./docs_src/` directory.
65
+
```console
66
+
$ bash scripts/test-cov-html.sh
67
+
```
76
68
77
-
And those Python files are included/injected in the documentation when generating the site.
69
+
</div>
78
70
79
-
### Docs for tests
71
+
This command generates a directory `./htmlcov/`, if you open the file `./htmlcov/index.html` in your browser, you can explore interactively the regions of code that are covered by the tests, and notice if there is any region missing.
80
72
81
-
Most of the tests actually run against the example source files in the documentation.
73
+
## Docs
82
74
83
-
This helps making sure that:
75
+
First, make sure you set up your environment as described above, that will install all the requirements.
84
76
85
-
* The documentation is up to date.
86
-
* The documentation examples can be run as is.
87
-
* Most of the features are covered by the documentation, ensured by test coverage.
77
+
### Docs Live
88
78
89
79
During local development, there is a script that builds the site and checks for any changes, live-reloading:
90
80
91
81
<divclass="termy">
92
82
93
83
```console
94
-
$ bash scripts/docs-live.sh
84
+
$ python ./scripts/docs.py live
95
85
96
-
<span style="color: green;">[INFO]</span> - Building documentation...
97
-
<span style="color: green;">[INFO]</span> - Cleaning site directory
98
-
<span style="color: green;">[INFO]</span> - Documentation built in 2.74 seconds
99
-
<span style="color: green;">[INFO]</span> - Serving on http://127.0.0.1:8008
86
+
<span style="color: green;">[INFO]</span> Serving on http://127.0.0.1:8008
@@ -105,20 +94,71 @@ It will serve the documentation on `http://127.0.0.1:8008`.
105
94
106
95
That way, you can edit the documentation/source files and see the changes live.
107
96
108
-
## Tests
97
+
/// tip
109
98
110
-
There is a script that you can run locally to test all the code and generate coverage reports in HTML:
99
+
Alternatively, you can perform the same steps that scripts does manually.
100
+
101
+
Go into the docs director at `docs/`:
102
+
103
+
```console
104
+
$ cd docs/
105
+
```
106
+
107
+
Then run `mkdocs` in that directory:
108
+
109
+
```console
110
+
$ mkdocs serve --dev-addr 8008
111
+
```
112
+
113
+
///
114
+
115
+
#### Typer CLI (Optional)
116
+
117
+
The instructions here show you how to use the script at `./scripts/docs.py` with the `python` program directly.
118
+
119
+
But you can also use <ahref="https://typer.tiangolo.com/typer-cli/"class="external-link"target="_blank">Typer CLI</a>, and you will get autocompletion in your terminal for the commands after installing completion.
120
+
121
+
If you install Typer CLI, you can install completion with:
111
122
112
123
<divclass="termy">
113
124
114
125
```console
115
-
$ bash scripts/test.sh
126
+
$ typer --install-completion
127
+
128
+
zsh completion installed in /home/user/.bashrc.
129
+
Completion will take effect once you restart the terminal.
116
130
```
117
131
118
132
</div>
119
133
120
-
This command generates a directory `./htmlcov/`, if you open the file `./htmlcov/index.html` in your browser, you can explore interactively the regions of code that are covered by the tests, and notice if there is any region missing.
134
+
### Docs Structure
135
+
136
+
The documentation uses <ahref="https://www.mkdocs.org/"class="external-link"target="_blank">MkDocs</a>.
121
137
122
-
## Thanks
138
+
And there are extra tools/scripts in place in `./scripts/docs.py`.
123
139
124
-
Thanks for contributing! ☕
140
+
/// tip
141
+
142
+
You don't need to see the code in `./scripts/docs.py`, you just use it in the command line.
143
+
144
+
///
145
+
146
+
All the documentation is in Markdown format in the directory `./docs`.
147
+
148
+
Many of the tutorials have blocks of code.
149
+
150
+
In most of the cases, these blocks of code are actual complete applications that can be run as is.
151
+
152
+
In fact, those blocks of code are not written inside the Markdown, they are Python files in the `./docs_src/` directory.
153
+
154
+
And those Python files are included/injected in the documentation when generating the site.
155
+
156
+
### Docs for Tests
157
+
158
+
Most of the tests actually run against the example source files in the documentation.
159
+
160
+
This helps to make sure that:
161
+
162
+
* The documentation is up-to-date.
163
+
* The documentation examples can be run as is.
164
+
* Most of the features are covered by the documentation, ensured by test coverage.
0 commit comments