Skip to content

Commit

Permalink
docs: add relative links to various file references (#1392)
Browse files Browse the repository at this point in the history
## Context

<!-- Please include a summary of the change, with motivation and context
-->
<!-- Bonus: if you are comfortable writing one, please insert a
user-story https://en.wikipedia.org/wiki/User_story#Common_templates -->

Was just reading through the docs here on GH and saw a lot of references
to files that could have relative links to those files for easy click
through

## Details

<!-- Describe here how you address the issue -->

- when a specific file in the codebase was referenced, link to it
- did not otherwise change the formatting of the content and left it
as-is (e.g. bold text)

- also fix a few incorrect (moved?) locations:
  - `HomeDBManager.ts` now in `homedb/` dir
  - a few files missing extensions
- some incorrect extensions (e.g. was `.ts` but it's actually still
`.js`)
  - having links to the files makes it much easier to find these issues

- and standardize one file reference that was different from the rest
("Python sandbox in this code:" -> "Python sandbox in [...]")

## Related issues

<!-- If suggesting a new feature or change, please discuss it in an
issue first -->
<!-- If fixing a bug, there should be an issue describing it with steps
to reproduce -->
<!-- If this does not solve entirely the issue, make also a checklist of
what is done or not: -->

Made some other docs improvements in #1391

## Has this been tested?

<!-- Put an `x` in the box that applies: -->

- [n/a] 👍 yes, I added tests to the test suite
- [n/a] 💭 no, because this PR is a draft and still needs work
- [x] 🙅 no, because this is not relevant here
- [n/a] 🙋 no, because I need help <!-- Detail how we can help you -->

I double-checked all the links to ensure they worked properly. Also my
code editor (VS Code) would autocomplete the relative paths correctly
when I typed them as another form of check.
  • Loading branch information
agilgur5 authored Jan 21, 2025
1 parent e5c0976 commit b12b5d6
Show file tree
Hide file tree
Showing 4 changed files with 63 additions and 65 deletions.
8 changes: 3 additions & 5 deletions documentation/database.md
Original file line number Diff line number Diff line change
Expand Up @@ -52,14 +52,13 @@ _grist_Shares _gristsys_PluginData

### The migrations

The migrations are handled in the Python sandbox in this code:
https://github.com/gristlabs/grist-core/blob/main/sandbox/grist/migrations.py
The migrations are handled in the Python sandbox in [`sandbox/grist/migrations.py`](../sandbox/grist/migrations.py).

For more information, please consult [the documentation for migrations](./migrations.md).

## The Home Database

The home database may either be a SQLite or a PostgreSQL database depending on how the Grist instance has been installed. For details, please refer to the `TYPEORM_*` env variables in the [README](https://github.com/gristlabs/grist-core/blob/main/README.md#database-variables).
The home database may either be a SQLite or a PostgreSQL database depending on how the Grist instance has been installed. For details, please refer to the `TYPEORM_*` env variables in the [README](../README.md#database-variables).

Unless otherwise configured, the home database is a SQLite file. In the default Docker image, it is stored at this location: `/persist/home.sqlite3`.

Expand Down Expand Up @@ -293,5 +292,4 @@ Stores information related to the identification.

### The migrations

The database migrations are handled by TypeORM ([documentation](https://typeorm.io/migrations)). The migration files are located at `app/gen-server/migration` and are run at startup (so you don't have to worry about running them yourself).

The database migrations are handled by TypeORM ([documentation](https://typeorm.io/migrations)). The migration files are located at [`app/gen-server/migration`](../app/gen-server/migration) and are run at startup (so you don't have to worry about running them yourself).
20 changes: 10 additions & 10 deletions documentation/grainjs.md
Original file line number Diff line number Diff line change
Expand Up @@ -54,13 +54,13 @@ In Knockout, the `.peek()` method allows looking at an observable’s value quic

### Building DOM

Older Grist code builds DOM using the `dom()` function defined in `app/client/lib/dom.js`. It is entirely analogous to [dom() in GrainJS](https://github.com/gristlabs/grainjs/blob/master/docs/basics.md#dom-construction).
Older Grist code builds DOM using the `dom()` function defined in [`app/client/lib/dom.js`](../app/client/lib/dom.js). It is entirely analogous to [dom() in GrainJS](https://github.com/gristlabs/grainjs/blob/master/docs/basics.md#dom-construction).

The method `dom.on('click', (ev) => { ... })` allows attaching an event listener during DOM construction. It is similar to the same-named method in GrainJS ([dom.on](https://github.com/gristlabs/grainjs/blob/master/docs/basics.md#dom-events)), but is implemented actually using JQuery.

Methods `dom.onDispose`, and `dom.autoDispose` are analogous to GrainJS, but rely on Knockout’s cleanup.

For DOM bindings, which allow tying DOM properties to observable values, there is a `app/client/lib/koDom.js` module. For example:
For DOM bindings, which allow tying DOM properties to observable values, there is a [`app/client/lib/koDom.js`](../app/client/lib/koDom.js) module. For example:

```
import * as dom from 'app/client/lib/dom';
Expand All @@ -79,11 +79,11 @@ In place of GrainJS’s `dom.cls`, older code uses `kd.toggleClass` to toggle a

What GrainJS calls `dom.domComputed`, is called `kd.scope` in older code; and `dom.forEach` is called `kd.foreach` (all lowercase).

Observable arrays, primarily needed for `kd.foreach`, are implemented in `app/client/lib/koArray.js`. There is an assortment of tools around them, not particularly well organized.
Observable arrays, primarily needed for `kd.foreach`, are implemented in [`app/client/lib/koArray.js`](../app/client/lib/koArray.js). There is an assortment of tools around them, not particularly well organized.

### Old Disposables

We had to dispose resources before GrainJS, and the tools to simplify that live in `app/client/lib/dispose.js`. In particular, it provides a `Disposable` class, with a similar `this.autoDispose()` method to that of GrainJS.
We had to dispose resources before GrainJS, and the tools to simplify that live in [`app/client/lib/dispose.js`](../app/client/lib/dispose.js). In particular, it provides a `Disposable` class, with a similar `this.autoDispose()` method to that of GrainJS.

What GrainJS calls `this.onDispose()`, is called `this.autoDisposeCallback()` in older code.

Expand All @@ -105,14 +105,14 @@ This should help you understand what you see, and you may use it in new code if

The metadata of a Grist document, which drives the UI of the Grist application, is organized into a `DocModel`, which contains tables, each table with rows, and each row with a set of observables for each field:

* `DocModel` — in `app/client/models/DocModel`
* `MetaTableModel` — in `app/client/models/MetaTableModel` (for metadata tables, which Grist frontend understands and uses)
* `MetaRowModel` — in `app/client/models/MetaRowModel`. These have particular typed fields, and are enhanced with helpful computeds, according to the table to which they belong to, using classes in `app/client/models/entities`.
* `DataTableModel` — in `app/client/models/DataTableModel` (for user-data tables, which Grist can only treat generically)
* `DataRowModel` — in `app/client/models/DataRowModel`.
* `DocModel` — in [`app/client/models/DocModel.ts`](../app/client/models/DocModel.ts)
* `MetaTableModel` — in [`app/client/models/MetaTableModel.js`](../app/client/models/MetaTableModel.js) (for metadata tables, which Grist frontend understands and uses)
* `MetaRowModel` — in [`app/client/models/MetaRowModel.js`](../app/client/models/MetaRowModel.js). These have particular typed fields, and are enhanced with helpful computeds, according to the table to which they belong to, using classes in [`app/client/models/entities`](../app/client/models/entities/).
* `DataTableModel` — in [`app/client/models/DataTableModel.js`](../app/client/models/DataTableModel.js) (for user-data tables, which Grist can only treat generically)
* `DataRowModel` — in [`app/client/models/DataRowModel.ts`](../app/client/models/DataRowModel.ts).
* `BaseRowModel` — base class for `MetaRowModel` and `DataRowModel`.

A RowModel contains an observable for each field. While there is old-style code that uses these observables, they all remain knockout observables.
A `RowModel` contains an observable for each field. While there is old-style code that uses these observables, they all remain knockout observables.

Note that new code can use these knockout observables fairly seemlessly. For instance, a knockout observable can be used with GrainJS dom-methods, or as a dependency of a GrainJS computed.

Expand Down
6 changes: 3 additions & 3 deletions documentation/migrations.md
Original file line number Diff line number Diff line change
@@ -1,8 +1,8 @@
# Migrations

If you change Grist schema, i.e. the schema of the Grist metadata tables (in `sandbox/grist/schema.py`), you'll have to increment the `SCHEMA_VERSION` (on top of that file) and create a migration. A migration is a set of actions that would get applied to a document at the previous version, to make it satisfy the new schema.
If you change Grist schema, i.e. the schema of the Grist metadata tables (in [`sandbox/grist/schema.py`](../sandbox/grist/schema.py)), you'll have to increment the `SCHEMA_VERSION` (on top of that file) and create a migration. A migration is a set of actions that would get applied to a document at the previous version, to make it satisfy the new schema.

To add a migration, add a function to `sandbox/grist/migrations.py`, of this form (using the new version number):
To add a migration, add a function to [`sandbox/grist/migrations.py`](../sandbox/grist/migrations.py), of this form (using the new version number):
```lang=python
@migration(schema_version=11)
def migration11(tdset):
Expand All @@ -19,7 +19,7 @@ If you are doing anything other than adding a column or a table, you must read t

Migrations are tricky. Normally, we think about the software we are writing, but migrations work with documents that were created by an older version of the software, which may not have the logic you think our software has, and MAY have logic that the current version knows nothing about.

This is why migrations code uses its own "dumb" implementation for loading and examining data (see `sandbox/grist/table_data_set.py`), because trying to load an older document using our primary code base will usually fail, since the document will not satisfy our current assumptions.
This is why migrations code uses its own "dumb" implementation for loading and examining data (see [`sandbox/grist/table_data_set.py`](../sandbox/grist/table_data_set.py)), because trying to load an older document using our primary code base will usually fail, since the document will not satisfy our current assumptions.

## Restrictions

Expand Down
Loading

0 comments on commit b12b5d6

Please sign in to comment.