Skip to content

Commit

Permalink
Improved docs
Browse files Browse the repository at this point in the history
  • Loading branch information
joepio committed Dec 4, 2023
1 parent ae1b5d1 commit 3769ae2
Show file tree
Hide file tree
Showing 18 changed files with 580 additions and 606 deletions.
2 changes: 2 additions & 0 deletions Earthfile
Original file line number Diff line number Diff line change
Expand Up @@ -121,9 +121,11 @@ e2e:
docs-pages:
RUN cargo install mdbook
RUN cargo install mdbook-linkcheck
RUN cargo install mdbook-sitemap-generator
RUN curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.5/install.sh | bash
RUN bash -c "source $HOME/.nvm/nvm.sh && nvm install 20 && npm install -g netlify-cli"
COPY --keep-ts docs /docs
WORKDIR /docs
RUN mdbook build
RUN mdbook-sitemap-generator -d docs.atomicdata.dev -o /docs/book/html/sitemap.xml
RUN --secret NETLIFY_AUTH_TOKEN=NETLIFY_TOKEN bash -c "source $HOME/.nvm/nvm.sh && netlify deploy --dir /docs/book/html --prod --auth $NETLIFY_AUTH_TOKEN --site atomic-docs"
330 changes: 2 additions & 328 deletions README.md

Large diffs are not rendered by default.

2 changes: 1 addition & 1 deletion browser/CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -289,7 +289,7 @@ This changelog covers all three packages, as they are (for now) updated as a who

## v0.26.2

- Add [Typedoc documentation](https://atomicdata-dev.github.io/atomic-data-browser/docs/modules.html) #100
- Add [Typedoc documentation](https://atomic-docs.netlify.app/) #100
- Fix bug not showing resource form fields
- Fix circular parent handling in `canWrite`
- Update references to changed resources #102
Expand Down
133 changes: 2 additions & 131 deletions browser/svelte/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,134 +3,5 @@
An implementation of Atomic Data for [Svelte](https://svelte.dev/).
This library is still at an early stage and the API is subject to change.

[See open source example project built with @tomic/svelte.](https://github.com/ontola/wonenatthepark)

## Quick Examples

### Getting a resource and displaying one of its properties

```html
<script lang="ts">
import { getResource, getValue } from '@tomic/svelte';
import { Core } from '@tomic/lib';
const resource = getResource<Core.Agent>('https://example.com/user1');
</script>

<h1>{$resource.props.name}</h1>
```

### Changing the value of a property with an input field

```html
<script lang="ts">
import { getResource, getValue, setValue } from '@tomic/svelte';
import { core, Core } from '@tomic/lib';
const resource = getResource<Core.Agent>('https://example.com/user1');
const name = getValue(resource, core.properties.name); // Writable<string>
</script>

<input bind:value="{$name}" />
```

## Getting started

Install the library with your preferred package manager:

```sh
npm install -S @tomic/svelte @tomic/lib
```

```sh
yarn add @tomic/svelte @tomic/lib
```

```sh
pnpm add @tomic/svelte @tomic/lib
```

Initialise the store

```html
// App.svelte

<script lang="ts">
import { initStore } from '@tomic/svelte';
import { Store } from '@tomic/lib';
onMount(() => {
// This is where you configure your atomic data store.
const store = new Store();
initStore(store);
});
</script>

// do sveltey things
```

You can now access this store from any component in your app with the store store.

```svelte
// Some random component.svelte
<script lang="ts">
import { store } from '@tomic/svelte';
const resource = $store.getResourceLoading('https://atomicdata.dev/documents/tgzamh5hk2t');
</script>
```

However, this resource does not update when some of its data changes somewhere else in your app.
That's where the `getResource` and `getValue` functions come in handy.

To get a value and display it in your component we first retrieve (or create) a resource from the store with `getResource` and then get its value with `getValue`.

```html
// Some random component.svelte

<script lang="ts">
import { getResource, getValue } from '@tomic/svelte';
import { core } from '@tomic/lib';
const resource = getResource('https://example.com/');
const name = getValue(resource, core.properties.name);
</script>

<main>
<h1>{$name}</h1>
...
</main>
```

Updating the values of a resource is super simple, just do what you would normally do with a writable svelte store:

```ts
const value = getValue(resource, core.properties.name);

$value = 'New Value';
```

The value now updates and changes will permeate through the store.

## Typescript

This library is build using typescript and is fully typed. To full advantage of Atomic Data's strong type system use [@tomic/cli](https://www.npmjs.com/package/@tomic/cli) to generate types using Ontologies. These can then be used like this:

```html
<script lang="ts">
import { getResource, getValue } from '@tomic/svelte';
import { core } from '@tomic/lib';
// User 'app' ontology generated using @tomic/cli
import { Person, app } from './ontologies';
const resource = getResource<Person>('https://myapp.com/users/me'); // Readable<Resource<Person>>
const name = getValue(resource, core.properties.name); // Writable<string>
const hobbies = getValue(resource, app.properties.hobbies); // Writable<string[]>
</script>

<main>
<h1>{$name}</h1>
...
</main>
```
- [See open source example project built with @tomic/svelte.](https://github.com/ontola/wonenatthepark)
- [Docs](https://docs.atomicdata.dev/svelte)
24 changes: 16 additions & 8 deletions docs/src/SUMMARY.md
Original file line number Diff line number Diff line change
@@ -1,10 +1,26 @@
## Table of contents

# What is Atomic Data

* [Atomic Data Overview](atomic-data-overview.md)
* [Motivation](motivation.md)
* [Strategy, history and roadmap](roadmap.md)
* [When (not) to use it](when-to-use.md)

# AtomicServer

* [AtomicServer](atomicserver/intro.md)
* [Installation](atomicserver/installation.md)
* [FAQ & troubleshooting](atomicserver/faq.md)
* [GUI](atomicserver/gui.md)
* [API](atomicserver/API.md)
* [Create & publish data](atomizing.md)
* [Creating a JSON-AD file](create-json-ad.md)
* [Software and libraries](tooling.md)
* [Upgrade your existing project](interoperability/upgrade.md)
* [With React](usecases/react.md)
* [With Svelte](svelte.md)

# Specification (core)

* [What is Atomic Data?](core/concepts.md)
Expand Down Expand Up @@ -32,13 +48,6 @@
* [Collections, filtering, sorting](schema/collections.md)
* [Uploading and downloading files](files.md)

# Create Atomic Data

* [Atomizing](atomizing.md)
* [Using Atomic-Server](atomic-server.md)
* [Creating a JSON-AD file](create-json-ad.md)
* [Upgrade your existing project](interoperability/upgrade.md)

# Use Atomic Data

* [Interoperability and comparisons](interoperability/intro.md)
Expand All @@ -59,7 +68,6 @@
* [Data Catalog](usecases/data-catalog.md)
* [Education](usecases/education.md)
* [Food labels](usecases/food-labels.md)
* [**Software and libraries**](tooling.md)

-----------

Expand Down
2 changes: 1 addition & 1 deletion docs/src/atomic-data-overview.md
Original file line number Diff line number Diff line change
Expand Up @@ -33,7 +33,7 @@ Atomic Data Extended is a set of extra modules (on top of Atomic Data Core) that
Atomic Data has been designed to be very easy to create and host.
In the Atomizing section, we'll show you how you can create Atomic Data in three ways:

- [Using Atomic Server, from your browser](atomic-server.md)
- [Using Atomic Server, from your browser](atomicserver/intro.md)
- [By creating JSON-AD (and optionally importing it)](create-json-ad.md)
- [By upgrading your existing application](interoperability/upgrade.md)

Expand Down
124 changes: 0 additions & 124 deletions docs/src/atomic-server.md
Original file line number Diff line number Diff line change
@@ -1,124 +0,0 @@
# Creating Atomic Data using Atomic-Server

Here is everything you need to get started:

- [Atomic-Server and its features](#atomic-server-and-its-features)
- [Running Atomic-Server locally (optional)](#running-atomic-server-locally-optional)
- [Creating an Agent](#creating-an-agent)
- [Creating your first Atomic Data](#creating-your-first-atomic-data)
- [There's more!](#theres-more)

## Atomic-Server and its features

[`Atomic-Server`](https://github.com/atomicdata-dev/atomic-server/blob/master/server/README.md) is the _reference implementation_ of the Atomic Data Core + Extended specification.
It was developed parallel to this specification, and it served as a testing ground for various ideas (some of which didn't work, and some of which ended up in the spec).

Atomic-Server is a graph database server for storing and sharing typed linked data.
It's free, open source (MIT license), and has a ton of features:

- ⚛️ **Dynamic schema validation** / type checking using [Atomic Schema](https://docs.atomicdata.dev/schema/intro.html). Combines safety of structured data with the
- 🚀 **Fast** (1ms responses on my laptop)
- 🪶 **Lightweight** (15MB binary, no runtime dependencies)
- 💻 **Runs everywhere** (linux, windows, mac, arm)
- 🌐 **Embedded server** with support for HTTP / HTTPS / HTTP2.0 and Built-in LetsEncrypt handshake.
- 🎛️ **Browser GUI included** powered by [atomic-data-browser](https://github.com/atomicdata-dev/atomic-data-browser). Features dynamic forms, tables, authentication, theming and more.
- 💾 **Event-sourced versioning** / history powered by [Atomic Commits](https://docs.atomicdata.dev/commits/intro.html)
- 🔄 **Synchronization using websockets**: communicates state changes with a client. Send a `wss` request to `/ws` to open a webscocket.
- 🧰 **Many serialization options**: to JSON, [JSON-AD](https://docs.atomicdata.dev/core/json-ad.html), and various Linked Data / RDF formats (RDF/XML, N-Triples / Turtle / JSON-LD).
- 🔎 **Full-text search** with fuzzy search and various operators, often <3ms responses.
- 📖 **Pagination, sorting and filtering** using [Atomic Collections](https://docs.atomicdata.dev/schema/collections.html)
- 🔐 **Authorization** (read / write permissions) and Hierarchical structures powered by [Atomic Hierarchy](https://docs.atomicdata.dev/hierarchy.html)
- 📲 **Invite and sharing system** with [Atomic Invites](https://docs.atomicdata.dev/invitations.html)
- 📂 **File management**: Upload, download and preview attachments.
- 🖥️ **Desktop app**: Easy desktop installation, with status bar icon, powered by [tauri](https://github.com/tauri-apps/tauri/).

## Running Atomic-Server locally (optional)

In this guide, we'll can simply use `atomicdata.dev` in our browser without installing anything.
So you can skip this step and go to _Creating your first Atomic Data_.
But if you want to, you can run Atomic-Server on your machine in a couple of ways:

- **Using a desktop installer**: download a desktop release from the [`releases`](https://github.com/atomicdata-dev/atomic-server/releases) page and install it using your desktop GUI.
- **Using a binary**: download a binary release from the [`releases`](https://github.com/atomicdata-dev/atomic-server/releases) page and open it using a terminal.
- **Using Docker** is probably the quickest: `docker run -p 80:80 -v atomic-storage:/atomic-storage joepmeneer/atomic-server`.
- **Using Cargo**: `cargo install atomic-server` and then run `atomic-server` to start.

_[Atomic-Server's README](https://github.com/atomicdata-dev/atomic-server) contains more (and up-to-date) information about how to use it!_

Open your server in your browser.
By default, that's [`http://localhost:9883`](http://localhost:9883).
Fun fact: `&#9883;` is HTML entity code for the Atom icon: ⚛.

The first screen should show you your [_Drive_](https://atomicdata.dev/classes/Drive).
You can think of this as your root folder.
It is the resource hosted at the root URL, effectively being the home page of your server.

There's an instruction on the screen about the `/setup` page.
Click this, and you'll get a screen showing an [_Invite_](https://atomicdata.dev/classes/Invite).
Normally, you could `Accept as new user`, but since you're running on `localhost`, you won't be able to use the newly created Agent on non-local Atomic-Servers.
Therefore, it may be best to create an Agent on some _other_ running server, such as the [demo Invite on AtomicData.dev](https://atomicdata.dev/invites/1).
And after that, copy the Secret from the `User settings` panel from AtomicData.dev, go back to your `localhost` version, and press `sign in`.
Paste the Secret, and voila! You're signed in.

Now, again go to `/setup`. This time, you can `Accept as {user}`.
After clicking, your Agent has gotten `write` rights for the Drive!
You can verify this by hovering over the description field, clicking the edit icon, and making a few changes.
You can also press the menu button (three dots, top left) and press `Data view` to see your agent after the `write` field.
Note that you can now edit every field.
You can also fetch your data now as various formats.

Try checking out the other features in the menu bar, and check out the `collections`.

Again, check out the [README](https://github.com/atomicdata-dev/atomic-server) for more information and guides!

Now, let's create some data.

## Creating an Agent

Before you can create new things on AtomicData.dev, you'll need an _Agent_.
This is your virtual User, which can create, sign and own things.

Simply open the [demo invite](https://atomicdata.dev/invites/1) and press accept.
And you're done!


## Creating your first Atomic Data

Now let's create a [_Class_](https://atomicdata.dev/classes/Class).
A Class represents an abstract concept, such as a `BlogPost` (which we'll do here).
We can do this in a couple of ways:

- Press the `+ icon` button on the left menu (only visible when logged in), and selecting Class
- Opening [Class](https://atomicdata.dev/classes/Class) and pressing `new class`
- Going to the [Classes Collection](https://atomicdata.dev/classes/) and pressing the plus icon

The result is the same: we end up with a form in which we can fill in some details.

Let's add a shortname (singular), and then a description.

After that, we'll add the `required` properties.
This form you're looking at is constructed by using the `required` and `recommended` Properties defined in `Class`.
We can use these same fields to generate our BlogPost resource!
Which fields would be required in a `BlogPost`?
A `name`, and a `description`, probably.

So click on the `+ icon` under `requires` and search for these Properties to add them.

Now, we can skip the `recommended` properties, and get right to saving our newly created `BlogPost` class.
So, press save, and now look at what you created.

Notice a couple of things:

- Your Class has its own URL.
- It has a `parent`, shown in the top of the screen. This has impact on the visibility and rights of your Resource. We'll get to that [later in the documentation](./hierarchy.md).

Now, go to the navigation bar, which is by default at the bottom of the window. Use its context menu to open the `Data View`.
This view gives you some more insight into your newly created data, and various ways in which you can serialize it.

## There's more!

This was just a very brief introduction to Atomic Server, and its features.
There's quite a bit that we didn't dive in to, such as versioning, file uploads, the collaborative document editor and more...
But by clicking around you're likely to discover these features for yourself.

In the next page, we'll dive into how you can create an publish JSON-AD files.
Loading

0 comments on commit 3769ae2

Please sign in to comment.