Scaffold ToC for consolidated SDK docs

source/examples/MissingPlaceholders/api.cpp

@@ -0,0 +1 @@
+// The C++ SDK does not currently support this API.

source/examples/MissingPlaceholders/api.cs

@@ -0,0 +1 @@
+// The .NET SDK does not currently support this API.

source/examples/MissingPlaceholders/api.dart

@@ -0,0 +1 @@
+// The Flutter SDK does not currently support this API.

source/examples/MissingPlaceholders/api.java

@@ -0,0 +1 @@
+// The Java SDK does not support this API.

source/examples/MissingPlaceholders/api.js

@@ -0,0 +1 @@
+// The Node.js SDK does not currently support this API.

source/examples/MissingPlaceholders/api.kt

@@ -0,0 +1 @@
+// The Kotlin SDK does not currently support this API.

source/examples/MissingPlaceholders/api.m

@@ -0,0 +1 @@
+// The Swift SDK does not currently support this API.

source/examples/MissingPlaceholders/api.swift

@@ -0,0 +1 @@
+// The Swift SDK does not currently support this API.

source/examples/MissingPlaceholders/api.ts

@@ -0,0 +1 @@
+// This API is not currently available in TypeScript.

source/examples/MissingPlaceholders/example.cpp

@@ -0,0 +1,2 @@
+// The documentation does not currently have this code example in C++.
+// Please refer to the other languages or related pages for example code.

source/examples/MissingPlaceholders/example.cs

@@ -0,0 +1,2 @@
+// The documentation does not currently have this code example in C#.
+// Please refer to the other languages or related pages for example code.

source/examples/MissingPlaceholders/example.dart

@@ -0,0 +1,2 @@
+// The documentation does not currently have this code example in Dart.
+// Please refer to the other languages or related pages for example code.

source/examples/MissingPlaceholders/example.java

@@ -0,0 +1,2 @@
+// The documentation does not currently have this code example in Java.
+// Please refer to the other languages or related pages for example code.

source/examples/MissingPlaceholders/example.js

@@ -0,0 +1,2 @@
+// The documentation does not currently have this code example in JavaScript.
+// Please refer to the other languages or related pages for example code.

source/examples/MissingPlaceholders/example.kt

@@ -0,0 +1,2 @@
+// The documentation does not currently have this code example in Kotlin.
+// Please refer to the other languages or related pages for example code.

source/examples/MissingPlaceholders/example.m

@@ -0,0 +1,2 @@
+// The documentation does not currently have this code example in Objective-C.
+// Please refer to the other languages or related pages for example code.

source/examples/MissingPlaceholders/example.swift

@@ -0,0 +1,2 @@
+// The documentation does not currently have this code example in Swift.
+// Please refer to the other languages or related pages for example code.

source/examples/MissingPlaceholders/example.ts

@@ -0,0 +1,2 @@
+// The documentation does not currently have this code example in TypeScript.
+// Please refer to the other languages or related pages for example code.

source/frameworks.txt

@@ -0,0 +1,31 @@
+.. _sdks-build-with-frameworks:
+
+=====================
+Build with Frameworks
+=====================
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 2
+   :class: singlecol
+
+.. toctree::
+   :titlesonly:
+
+   Electron </frameworks/electron>
+   Flutter </frameworks/flutter>
+   Maui </frameworks/maui>
+   .NET </frameworks/dotnet>
+   React Native </frameworks/react-native>
+   SwiftUI </frameworks/swiftui>
+
+The following pages contain information about building with specific
+frameworks using Atlas Device SDK:
+
+- :ref:`sdks-build-with-electron`
+- :ref:`sdks-build-with-flutter`
+- :ref:`sdks-build-with-maui`
+- :ref:`sdks-build-with-dotnet`
+- :ref:`sdks-build-with-react-native`
+- :ref:`sdks-build-with-swiftui`

source/frameworks/dotnet.txt

@@ -0,0 +1,14 @@
+.. _sdks-build-with-dotnet:
+
+===============
+Build with .NET
+===============
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 2
+   :class: singlecol
+
+Placeholder page for information about building with .NET. (This may
+be a directory depending on how much content we have/need.)

source/frameworks/electron.txt

@@ -0,0 +1,14 @@
+.. _sdks-build-with-electron:
+
+===================
+Build with Electron
+===================
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 2
+   :class: singlecol
+
+Placeholder page for information about building with Electron. (This may
+be a directory as we have two pages for this?)

source/frameworks/flutter.txt

@@ -0,0 +1,14 @@
+.. _sdks-build-with-flutter:
+
+==================
+Build with Flutter
+==================
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 2
+   :class: singlecol
+
+Placeholder page for information about building with Flutter. (This may
+be a directory depending on how much content we have/need.)

source/frameworks/maui.txt

@@ -0,0 +1,14 @@
+.. _sdks-build-with-maui:
+
+===============
+Build with Maui
+===============
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 2
+   :class: singlecol
+
+Placeholder page for information about building with Maui. (This may
+be a directory depending on how much content we have/need.)

source/frameworks/react-native.txt

@@ -0,0 +1,16 @@
+.. _sdks-build-with-react-native:
+
+=======================
+Build with React Native
+=======================
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 2
+   :class: singlecol
+
+Placeholder page for information about building with React Native
+and ``@realm/react``.
+
+This will be a directory with content.

source/frameworks/swiftui.txt

@@ -0,0 +1,15 @@
+.. _sdks-build-with-swiftui:
+
+==================
+Build with SwiftUI
+==================
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 2
+   :class: singlecol
+
+Placeholder page for information about building with SwiftUI.
+
+This will be a directory with SwiftUI content.

source/includes/api-details/cpp/crud/create-embedded-object-description.rst

@@ -0,0 +1,16 @@
+To create an embedded object, assign the raw pointer of the embedded 
+object to a parent object's property. Move the parent object into 
+the realm using the :cpp-sdk:`Realm.add() function <structrealm_1_1db.html>` 
+inside of a write transaction.
+
+In this example, we assign the raw pointer of the embedded object - 
+``ContactDetails *`` - to the embedded object property of the parent 
+object - ``Business.contactDetails``.
+
+Then, we add the ``business`` object to the realm. This copies the 
+``business`` and ``contactDetails`` objects to the realm. 
+
+Because ``ContactDetails`` is an embedded object, it does not have
+its own lifecycle independent of the main ``Business`` object. 
+If you delete the ``Business`` object, this also deletes the 
+``ContactDetails`` object.

source/includes/api-details/cpp/crud/create-procedure.rst

@@ -0,0 +1,17 @@
+#. Open a write transaction with 
+   :cpp-sdk:`Realm.write() function <structrealm_1_1db.html>`.
+
+#. Instantiate an unmanaged object instance within the ``realm`` namespace.
+
+#. Move the unmanaged object instance into the database using the 
+   :cpp-sdk:`Realm.add() function <structrealm_1_1db.html>`.
+
+   When you move an object into a realm, this consumes the object as an rvalue.
+   You must use the managed object for any data access or observation. If
+   you would like to immediately work with the object, return a managed
+   version of the object.
+
+#. Work with the persisted SDK object through the returned instance. Note that
+   this *does not* apply to asymmetric objects, which are write-only. Once an
+   asymmetric object is synced, it is deleted from the database. You cannot
+   read, update, or delete an asymmetric object from the device.

source/includes/api-details/cpp/crud/create-realm-object-description.rst

@@ -0,0 +1,10 @@
+To create an object, you must instantiate it using the ``realm`` namespace. 
+Move the object into the realm using the
+:cpp-sdk:`Realm.add() function <structrealm_1_1db.html>` 
+inside of a write transaction.
+
+When you move an object into a realm, this consumes the object as an 
+rvalue. You must use the managed object for any data access or observation.
+In this example, copying the ``dog`` object into the realm consumes 
+it as an rvalue. You can return the managed object to continue to work 
+with it.

source/includes/api-details/csharp/crud/create-procedure.rst

@@ -0,0 +1,17 @@
+#. Open a write transaction with the
+   :dotnet-sdk:`Realm.Write() <reference/Realms.Realm.html#Realms_Realm_Write__1_System_Func___0__>`
+   or :dotnet-sdk:`Realm.WriteAsync() <reference/Realms.Realm.html#Realms_Realm_WriteAsync_System_Action_System_Threading_CancellationToken_>`
+   methods. Prefer ``WriteAsync()`` to avoid blocking the UI, unless blocking
+   the UI is desired.
+
+#. Instantiate an unmanaged object instance whose object model implements one
+   of the SDK's object interfaces. For more information, refer to 
+   :ref:`sdks-object-models`.
+
+#. Pass the unmanaged object instance to the
+   :dotnet-sdk:`Realm.Add() method <reference/Realms.Realm.html#Realms_Realm_Add__1___0_System_Boolean_>`
+   to persist the object data to the database.
+
+   Note that asymmetric objects are write-only. Once an asymmetric object is
+   synced, it is deleted from the device database. You cannot read, update, or
+   delete an asymmetric object from the device.

source/includes/api-details/csharp/crud/create-realm-object-description.rst

@@ -0,0 +1,5 @@
+The following code shows two methods for creating a new Realm object. In the 
+first example, we create the object first, and then add it to the realm within 
+a :dotnet-sdk:`WriteAsync() <reference/Realms.Realm.html#Realms_Realm_WriteAsync_System_Action_System_Threading_CancellationToken_>`
+method. In the second example, we create the document within the ``WriteAsync`` 
+block, which returns a realm object we can further work with.

source/includes/api-details/dart/crud/create-asymmetric-object-description.rst

@@ -0,0 +1,2 @@
+Once you have an open Realm, you can create an asymmetric object inside
+a write transaction. Pass your object data to ``realm.ingest``.

source/includes/api-details/dart/crud/create-procedure.rst

@@ -0,0 +1,16 @@
+#. Open a write transaction with a
+   :flutter-sdk:`Realm.write() <realm/Realm/write.html>` or 
+   :flutter-sdk:`Realm.writeAsync() <realm/Realm/writeAsync.html>` methods.
+
+#. Instantiate an unmanaged object instance whose ``RealmObject`` model 
+   has been successfully created, generated, and imported into the file. 
+   For more information, refer to :ref:`sdks-object-models`.
+
+#. Pass the unmanaged object instance to the 
+   :flutter-sdk:`Realm.add() method <realm/Realm/add.html>`
+   to persist the object data to the database. You can return managed objects
+   from the write transaction block to observe or work with them immediately.
+
+   Note that asymmetric objects are write-only. Once an asymmetric object is
+   synced, it is deleted from the device database. You cannot read, update, or
+   delete an asymmetric object from the device.

source/includes/api-details/dart/crud/create-realm-object-description.rst

@@ -0,0 +1,16 @@
+Once you've opened a database, you can create objects within it using a
+:flutter-sdk:`Realm.write() <realm/Realm/write.html>` transaction block.
+
+.. code-block:: dart
+
+   realm.write((){
+     // ...write data to realm
+   });
+
+You can also return values from the write transaction callback function.
+
+.. warning:: Write RealmObjects to One Realm File
+
+   You can only write ``RealmObjects`` to a single realm file.
+   If you already wrote a ``RealmObject`` to one realm file,
+   the SDK throws a ``RealmException`` if you try to write it to another database.

source/includes/api-details/generic/crud/create-asymmetric-object-description.rst

@@ -0,0 +1,2 @@
+To create an asymmetric object, initialize an asymmetric object type and add
+it to the database in a write transaction:

source/includes/api-details/generic/crud/create-embedded-object-description.rst

@@ -0,0 +1,2 @@
+To create an embedded object, assign an instance of the embedded object
+to a parent object's property:

source/includes/api-details/java/crud/create-asymmetric-object-not-supported.rst

@@ -0,0 +1,2 @@
+:ref:`Data Ingest <optimize-data-ingest>` is not supported in the Java SDK.
+To stream data from the client application to Atlas, use the Kotlin SDK.

source/includes/api-details/java/crud/create-procedure.rst

@@ -0,0 +1,14 @@
+#. Open a write transaction with the
+   :java-sdk:`realm.executeTransaction() <io/https://www.mongodb.com/docs/realm-sdks/java/latest/io/realm/Realm.html#executeTransaction(io.realm.Realm.Transaction)>` or 
+   :java-sdk:`realm.executeTransactionAsync() <io/realm/Realm.html#executeTransactionAsync(io.realm.Realm.Transaction,io.realm.Realm.Transaction.OnSuccess,io.realm.Realm.Transaction.OnError)>` methods.
+
+#. Instantiate an unmanaged object instance whose model subclasses 
+   :java-sdk:`RealmObject <io/realm/RealmObject.html>` or implements the
+   :java-sdk:`RealmModel <io/realm/RealmModel.html>` interface. For more
+   information, refer to :ref:`sdks-object-models`.
+
+#. Pass the unmanaged object instance to the 
+   :java-sdk:`realm.createObject() method <io/realm/Realm.html#createObject(java.lang.Class)>`
+   or the 
+   :java-sdk:`createObjectFromJson() method <io/realm/Realm.html#createObjectFromJson-java.lang.Class-java.lang.String->`
+   to create an SDK object instance.

source/includes/api-details/java/crud/create-realm-object-description.rst

@@ -0,0 +1,7 @@
+Use :java-sdk:`realm.createObject() <io/realm/Realm.html#createObject(java.lang.Class)>`
+in a transaction to create a persistent instance of a Realm object in a
+realm. You can then modify the returned object with other field values
+using accessors and mutators.
+
+The following example demonstrates how to create an object with 
+:java-sdk:`createObject() <io/realm/Realm.html#createObject-java.lang.Class-java.lang.Object->`:

source/includes/api-details/javascript/crud/create-asymmetric-object-description.rst

@@ -0,0 +1,4 @@
+You can create an asymmetric object inside a write transaction using 
+:js-sdk:`Realm.create() <classes/Realm-1.html#create>`. When creating an 
+asymmetric object, ``Realm.create()`` returns ``undefined`` rather than the
+object itself.

source/includes/api-details/javascript/crud/create-procedure.rst

@@ -0,0 +1,16 @@
+#. Open a write transaction with the
+   :js-sdk:`Realm.write() <classes/Realm-1.html#write>` method.
+
+#. Instantiate an unmanaged object instance of your JavaScript class or a
+   class that extends :js-sdk:`Realm.object <classes/Realm.Object.html>`.
+   For more information, refer to :ref:`sdks-object-models`.
+
+#. Pass the unmanaged object instance to the 
+   :js-sdk:`Realm.create() <classes/Realm-1.html#create>` method
+   to persist the object data to the database. You can assign the new managed
+   object to a variable or return it from the write transaction block to 
+   observe or work with it immediately.
+
+   Note that asymmetric objects are write-only. Once an asymmetric object is
+   synced, it is deleted from the device database. You cannot read, update, or
+   delete an asymmetric object from the device.

source/includes/api-details/javascript/crud/create-realm-object-description.rst

@@ -0,0 +1,5 @@
+To add an object to a realm, instantiate it as you would any other object
+and then pass it to :js-sdk:`Realm.create() <classes/Realm-1.html#create>` inside of a
+write transaction. If the realm's :ref:`schema <node-realm-schema>` includes
+the object type and the object conforms to the schema, then Realm
+stores the object, which is now *managed* by the realm.

source/includes/api-details/kotlin/crud/create-asymmetric-object-description.rst

@@ -0,0 +1,13 @@
+Unlike other SDK objects, you *do not* use the ``copyToRealm()`` method to
+create it. Instead, you use a special ``insert()`` extension method to insert 
+it into the database.
+
+To create a new ``AsymmetricRealmObject`` instance, instantiate a 
+new object of an
+:ref:`asymmetric object type <kotlin-asymmetric-objects>` using 
+`insert() <{+kotlin-sync-prefix+}io.realm.kotlin.mongodb.ext/insert.html>`__.
+
+In the following example, we instantiate a new ``WeatherSensor``
+object and pass it to ``insert()`` within a write transaction:
+
+.. versionadded:: 1.10.0

source/includes/api-details/kotlin/crud/create-embedded-object-description.rst

@@ -0,0 +1,10 @@
+In the following example, we instantiate a new  ``Contact`` object with 
+an embedded ``Address``, which contains a ``Contact`` object and an embedded
+``Country`` object:
+
+.. literalinclude:: /examples/generated/kotlin/CreateTest.snippet.create-one-embedded-object.kt 
+    :language: kotlin
+
+We also instantiate a new ``Business`` object with a 
+list of embedded ``Address`` objects, which also contain ``Contact`` 
+objects and embedded ``Country`` objects:

source/includes/api-details/kotlin/crud/create-procedure.rst

@@ -0,0 +1,35 @@
+#. Open a write transaction with `realm.write()
+   <{+kotlin-local-prefix+}io.realm.kotlin/-realm/write.html>`__ or
+   `realm.writeBlocking()
+   <{+kotlin-local-prefix+}io.realm.kotlin/-realm/write-blocking.html>`__.
+
+#. Instantiate an unmanaged object instance with the class 
+   constructor. You can use an `apply block
+   <https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/apply.html>`__
+   to configure multiple properties at once.
+
+#. Pass the unmanaged object instance to `copyToRealm()
+   <{+kotlin-local-prefix+}io.realm.kotlin/-mutable-realm/copy-to-realm.html>`__
+   to persist the object data to the database. This method returns a
+   live managed instance of the object. 
+
+   .. important:: Asymmetric Objects Use Insert()
+
+      Asymmetric objects are special write-only objects that do not 
+      persist to the database. They *do not* use ``copyToRealm()``. 
+      Instead, you pass the asymmetric object instance to the 
+      ``insert()`` extension method within a write transaction.
+      Refer to the :ref:`sdks-create-asymmetric-object` section 
+      on this page for more information.
+
+#. Work with the persisted SDK object through the returned instance. The live
+   object is accessible until the write transaction completes. Note that this
+   *does not* apply to asymmetric objects, which are write-only. Once an
+   asymmetric object is synced, it is deleted from the device database. You
+   cannot read, update, or delete an asymmetric object from the device.
+
+.. note:: Frozen Objects
+
+   In Kotlin, objects returned from a write closure become frozen objects when
+   the write transaction completes. For more information, refer to 
+   :ref:`kotlin-frozen-architecture`.