docs: add relative links to various file references #1392
Conversation
- 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`)
- and standardize one file reference that was different from the rest ("Python sandbox in this code:" -> "Python sandbox in [...]")
There was a problem hiding this comment.
Overall LGTM. Thank you!
Some little improvements you may add:
- You may use absolute link (instead of using
../path/to/resource.ext, using/path/to/resource.ext), but if the document is moved elsewhere, the links are still valid; - In
documentation/overview.md⇒ Changes to documents, I see thatsandbox/grist/useractions.pyhas no link
| Maintains data for a metadata table, making it available as observable arrays of `MetaRowModel`s. The difference between metadata tables and user tables is that the Grist app knows what’s in metadata, and relies on it for its functionality. We also assume that metadata tables are small enough that we can instantiate [observables](https://github.com/gristlabs/grainjs/blob/master/docs/basics.md#observables) for all fields of all rows. | ||
| * `app/client/models/`**`DataTableModel.js`** | ||
| * [`app/client/models/`**`DataTableModel.js`**](../app/client/models/DataTableModel.js) | ||
| Maintains data for a user table, making it available as `LazyArrayModel`s (defined in the same file), which are used as the basis for `koDomScrolly` (see `app/client/lib/koDomScrolly.js` below). |
There was a problem hiding this comment.
You might add a link here too:
| Maintains data for a user table, making it available as `LazyArrayModel`s (defined in the same file), which are used as the basis for `koDomScrolly` (see `app/client/lib/koDomScrolly.js` below). | |
| Maintains data for a user table, making it available as `LazyArrayModel`s (defined in the same file), which are used as the basis for `koDomScrolly` (see [`app/client/lib/koDomScrolly.js`](/app/client/lib/koDomScrolly.js) below). |
There was a problem hiding this comment.
I actually specifically didn't add it to this one since this refers to "below", which has both a link and a description. As in, linking this one may make a reader miss the description, which goes against the intent of the text -- the intent of the text here is to make you scroll down rather than read the code
Nice catch! I added that in c61c8a7
Hmm, IIRC this might only be valid for GH-flavored markdown rendered on GH. My editor doesn't recognize this and tries opening an actual absolute link on my FS. So there's a trade-off to using absolute links -- let me know if you still want me to make that change |
From my prospective, it is acceptable as it is. |
|
I approved your PR, but please note that I don't have the rights for merging. You should wait for someone at GristLabs to do that. |
Context
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
when a specific file in the codebase was referenced, link to it
also fix a few incorrect (moved?) locations:
HomeDBManager.tsnow inhomedb/dir.tsbut it's actually still.js)and standardize one file reference that was different from the rest ("Python sandbox in this code:" -> "Python sandbox in [...]")
Related issues
Made some other docs improvements in #1391
Has this been tested?
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.