(DOCSP-12426): Build out Realm Studio documentation (#1053)

snooty.toml

@@ -41,7 +41,8 @@ toc_landing_pages = [
   "/node",
   "/react-native",
   "/web",
-  "/dotnet"
+  "/dotnet",
+  "/studio"
 ]
 
 [substitutions]

source/includes/find-realm-file-dotnet.rst

@@ -0,0 +1,4 @@
+.. code-block:: csharp
+
+   var realm = Realm.GetInstance();
+   Console.WriteLine($"Realm is located at: {realm.Config.DatabasePath}");

source/includes/find-realm-file-java.rst

@@ -0,0 +1,27 @@
+The filesystem used by Android emulators is not directly accessible 
+from the machine running Realm Studio. You must download the file
+from the emulator before you can access it.
+
+First, find the path of the file on the emulator:
+
+.. code-block:: java
+
+   // Run this on the device to find the path on the emulator
+   Realm realm = Realm.getDefaultInstance();
+   Log.i("Realm", realm.getPath());
+
+Then, download the file using ADB. You can do this while the app 
+is running.
+
+.. code-block:: java
+
+   > adb pull <path>
+
+You can also upload the modified file again using ADB, but only 
+when the app isn't running. Uploading a modified file while the 
+app is running can corrupt the file.
+
+.. code-block:: java
+
+   > adb push <file> <path>
+   

source/includes/find-realm-file-javascript.rst

@@ -0,0 +1,6 @@
+.. code-block:: javascript
+
+   // Get on-disk location of the default Realm
+   Realm.open({}).then(realm => {
+       console.log("Realm is located at: " + realm.path);
+   });

source/includes/find-realm-file-swift.rst

@@ -0,0 +1,6 @@
+.. code-block:: swift
+
+   // Get on-disk location of the default Realm
+   let realm = try! Realm()
+   print("Realm is located at:", realm.configuration.fileURL!)
+   

source/includes/realm-studio-export-class-definitions.rst

@@ -0,0 +1,11 @@
+To export updated class definitions:
+
+- Go to :guilabel:`File` > :guilabel:`Save model definitions`, and select
+  your preferred language. Supported languages include: Swift, JavaScript,
+  TypeScript, Java, Kotlin, and C#. 
+- Specify a name and destination for your new class definitions. Press
+  the :guilabel:`Save` button.
+
+If your destination directory does not already exist, Realm Studio creates 
+it. Inside, you'll find a file that contains a complete list of classes 
+and properties, including new additions.

source/includes/steps-create-realm-from-csv.yaml

@@ -0,0 +1,33 @@
+title: Browse to the Create Realm from CSV option
+ref: realm-studio-select-create-from-csv
+content: |
+  In Realm Studio, go to: :guilabel:`File` > :guilabel:`Create Realm from` > :guilabel:`CSV`
+---
+title: Open your CSV
+ref: realm-studio-open-csv
+content: |
+  Browse to the location of your CSV file, and select it.
+
+  Press the :guilabel:`Open` button.
+---
+title: Choose where to store the imported data
+ref: realm-studio-choose-where-to-store-imported-data
+content: |
+  Enter a name for the {+realm+} file that will be created from your CSV. 
+  
+  Browse to the location where you want to save it. 
+
+  Press the :guilabel:`Save` button.
+---
+title: Add more data to the {+realm+}
+ref: realm-studio-add-data-to-realm-created-from-csv
+content: |
+  When you create a new {+realm+} file from a CSV, you may get this message:
+    
+  "Failed to import data: Class name (name-of-file.csv) missing from schema"
+  
+  If this happens, press :guilabel:`OK`. You'll see that creating a {+realm+}
+  from your CSV has created a class definition, but there are no objects
+  in your {+realm+}. From here, you can :ref:`Import from a CSV<realm-studio-import-from-a-csv>` 
+  to populate your {+realm+} with object that map to the class definition 
+  you just created.

source/includes/steps-install-realm-studio.yaml

@@ -0,0 +1,47 @@
+title: Select a version
+ref: select-realm-studio-version
+content: |
+
+  The binaries listed on this page are always the latest version of 
+  Realm Studio.
+
+  If you open an older version of a {+realm+} file in a newer Realm Studio 
+  version, you may see a prompt to upgrade your {+realm+} file. Once 
+  upgraded, you cannot revert to the older file version. You may also 
+  need to upgrade your SDK to a version that supports the newer file format. 
+   
+  If you don't want to upgrade {+client-database+}, download an older 
+  version of Realm Studio. You can see a list of all releases at 
+  `Realm Studio Releases <https://studio-releases.realm.io/>`_. 
+  Click a version number to view a page listing enhancements, fixes, 
+  and file downloads.
+
+---
+title: Download the binary
+ref: download-realm-studio-binary
+content: |
+
+  Download and extract the correct binary for your operating system.
+
+  .. list-table::
+     :header-rows: 1
+     :class: index-table
+
+     * - Operating System
+       - Download
+
+     * - Linux
+       - `.AppImage <https://studio-releases.realm.io/latest/download/linux-appimage>`_
+
+     * - MacOS
+       - `.dmg <https://studio-releases.realm.io/latest/download/mac-dmg>`_
+   
+     * - Windows
+       - `.exe <https://studio-releases.realm.io/latest/download/win-setup>`_
+
+---
+title: Run the executable file
+ref: run-realm-studio-executable
+content: |
+
+  Run the executable file. Follow installer instructions.

source/includes/steps-realm-studio-create-object.yaml

@@ -0,0 +1,24 @@
+title: Select a class for the new object
+ref: realm-studio-create-object-select-class
+content: |
+  The left sidebar of Realm Studio displays the classes that comprise the 
+  schema. Select the class for the type of object you want to create.
+---
+title: Create the new object
+ref: realm-studio-create-the-new-object
+content: |
+  Once you've decided where to create your new object, you can do this in
+  two ways: 
+  
+  - Click the :guilabel:`Create {Class name}` button in the upper right
+    corner of the app
+  - Right click (or control click) anywhere in the main window to bring 
+    up the contextual menu, and select :guilabel:`Create new {Class name}`
+
+  Either option will open a dialog where you can set the properties
+  for the object. When you've specified the required properties, press the
+  :guilabel:`Create` button.
+
+  If you create an orphaned object that is not associated with a parent
+  object via a linking property, you'll need to add it manually to the
+  linked object. See: :ref:`Modify an Object <realm-studio-modify-an-object>`.

source/includes/steps-realm-studio-import-from-csv.yaml

@@ -0,0 +1,24 @@
+title: Browse to the Import from CSV option
+ref: realm-studio-import-from-csv-option
+content: |
+  In Realm Studio, go to: :guilabel:`File` > :guilabel:`Import data from` > :guilabel:`CSV`
+---
+title: Select a CSV to import
+ref: realm-studio-import-from-csv-select-csv
+content: |
+  Browse to the location of your CSV file, and select it.
+
+  Press the :guilabel:`Open` button.
+---
+title: Choose the destination class for your objects
+ref: realm-studio-import-from-csv-choose-destination-class
+content: |
+  You'll see a drop-down selector containing the available classes in
+  your {+realm+} file. Select the class where the imported data should
+  become objects.
+  
+  Press the :guilabel:`Import data` button.
+
+  Now you'll see newly-created objects created from the data you imported. 
+  Each object's properties map to the properties of the class you selected 
+  during import.

source/studio.txt

@@ -4,50 +4,39 @@
 Realm Studio
 ============
 
+.. toctree::
+   :titlesonly:
+   :hidden:
+
+   Install Realm Studio </studio/install>
+   Open a Realm File </studio/open-realm-file>
+   Explore a Realm File </studio/explore-realm-file>
+   Modify a Realm File </studio/modify-objects>
+   Modify Schema </studio/modify-schema>
+
 Get Started with Realm Studio
 -----------------------------
 
-Realm Studio is a developer tool for desktop operating systems that
-allows you to manage Realm Database instances. With Realm Studio, you
-can open and edit local and synced realms. It supports Mac, Windows, and
-Linux.
+Realm Studio is a visual tool to view, edit, and design {+client-database+} 
+files. With Realm Studio, developers can:
+
+- Query objects in the database
+- View live objects in realtime while running an app
+- Create, modify, and delete objects
+- Add classes and properties to the schema
+- Export the schema as class definitions in C#, Java, JavaScript, Kotlin, 
+  Swift, and TypeScript
+- Save and import changes into a client app or production database
 
 .. image:: /images/realm-studio.png
    :alt: A screenshot of Realm Studio
 
-See :github:`Releases on GitHub <realm/realm-studio/releases/latest>`:
-
-- `Download for Linux <https://studio-releases.realm.io/latest/download/linux-appimage>`_
-- `Download for Mac <https://studio-releases.realm.io/latest/download/mac-dmg>`_
-- `Download for Windows <https://studio-releases.realm.io/latest/download/win-setup>`_
-
-.. _find-the-default-realm-path:
-
-Find the Realm File(s)
-----------------------
-
-{+client-database+} stores a binary encoded version of every object and type in a
-realm in a single ``.realm`` file. The file is located at a specific path that
-you define when you open the realm.
-
-.. tabs-realm-languages::
-
-   .. tab::
-      :tabid: swift
-
-      In Swift app development, you can find the current path of the
-      default {+realm+} by pausing the simulator and using the LLDB console:
-
-      .. code-block:: swift
-
-         (lldb) po Realm.Configuration.defaultConfiguration.fileURL
-
-   .. tab::
-      :tabid: objective-c
-
-      In Objective-C app development, you can find the current path of the
-         default {+realm+} by pausing the simulator and using the LLDB console:
+View Realm Studio Releases
+--------------------------
 
-      .. code-block:: objective-c
+You can see a list of all releases at `Realm Studio Releases <https://studio-releases.realm.io/>`_. 
+Click a version number to view a page listing enhancements, fixes, and 
+file downloads for that version.
 
-         (lldb) po [RLMRealmConfiguration defaultConfiguration].fileURL
+Alternately, you can view :github:`Releases on GitHub <realm/realm-studio/releases/latest>`,
+as well as track and file issues for Realm Studio.

source/studio/explore-realm-file.txt

@@ -0,0 +1,79 @@
+.. _realm-studio-explore-realm-file:
+
+====================
+Explore a Realm File
+====================
+
+.. default-domain:: mongodb
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 2
+   :class: singlecol
+
+Overview
+--------
+
+When you open a {+realm+} file in Realm Studio, you can:
+
+- View live objects in realtime
+- Query objects in the {+realm+}
+- Export SDK model definitions
+
+This makes it a valuable tool for developing and debugging applications 
+backed by {+client-database+}. 
+
+View Live Objects in Realtime
+-----------------------------
+
+Realm Studio gives you the ability to view live objects while you're 
+running a client app in an emulator. You can see how functions in your 
+app are transforming objects in realtime. This is a powerful debugging 
+and development tool.
+
+To view live objects in Realm Studio, you'll need to :ref:`find your {+realm+} 
+file <realm-studio-find-a-realm-file>`. Once you know your {+realm+} file 
+path, you can open it in Realm Studio while your app is running.
+
+.. note::
+
+   Unfortunately, Android emulators do not support viewing live objects 
+   in Realm Studio. If you're developing for Android, you must download 
+   the file from the emulator before you can access it.
+
+Query Objects in the Realm
+--------------------------
+
+Realm Studio enables you to query the objects in the {+realm+} file. The 
+ability to do this in the {+realm+} via Realm Studio gives you a visual 
+tool to:
+
+- Quickly view query results
+- Experiment with query syntax
+- Validate the data in the {+realm+} file
+
+The Realm Studio query bar at the top of the main pane 
+accepts the :ref:`{+client-database+} JavaScript query syntax<node-client-query-engine>`. 
+You can query using:
+
+- Comparison operators
+- Logical operators
+- String operators
+
+You can also view a reference document that details the query options from 
+within Realm Studio. Press the :guilabel:`?` button next to the query bar.
+
+Export SDK Model Definitions
+----------------------------
+
+Realm Studio enables you to export model definitions, streamlining 
+cross-platform development.
+
+For example, you may be an iOS developer who has already created a 
+schema in an existing app. You now need to declare the same schema for 
+your Android app. Recreating that schema in another programming language 
+can be time-consuming and error-prone. Instead, you can open your {+realm+} 
+file in Realm Studio, and export the model definition in Java. 
+
+.. include:: /includes/realm-studio-export-class-definitions.rst