docs: update to reflect that RNTuple is the default writing format (#1624)

Updated docs to reflect RNTuple being the default writing format

Co-authored-by: Ianna Osborne <ianna.osborne@cern.ch>

Author: ariostas

docs-sphinx/basic.rst

@@ -924,6 +924,8 @@ Reading RNTuples
 
 TTree has been the default format to store large datasets in ROOT files for decades. However, it has slowly become outdated and is not optimized for modern systems. This is where the RNTuple format comes in. It is a modern serialization format that is designed with modern systems in mind and is planned to replace TTree in the coming years. `Version 1.0.0.0 <https://cds.cern.ch/record/2923186>`__ is out and will be supported "forever".
 
+Starting in Uproot v5.7.0, RNTuple is the default format for writing. When you use the dict-like syntax to write data to a file, Uproot will create an RNTuple instead of a TTree.
+
 RNTuples are deliberately simpler than TTrees by design. For the first time, there’s an official specification, making it much easier for third-party I/O tools like Uproot to support it. Uproot already supports reading the full RNTuple specification, meaning that you can read any RNTuple you find in the wild. It also already supports writing a large part of the specification, and intends to support as much as it makes sense for data analysis.
 
 To ease the transition into RNTuples, we are designing the interface to closely match the existing TTree interface. Many of the functionality explained in the previous subsections works in the same way. However, there the terminology is slightly different (e.g. "branch" becomes "field") and arguments may vary slightly, accordingly.
@@ -1145,8 +1147,10 @@ Writing TTrees to a file
 TTrees are a special type of object, just as TDirectories are special: data can be cumulatively added to them.
 
 :doc:`uproot.writing.writable.WritableTree` objects can be created using the :ref:`uproot.writing.writable.WritableDirectory.mktree` method that Uproot provides for TDirectories.
-Previously, they could be created by assigning TTree-like data to a name in a directory (e.g., ``file["tree"] = {"branch": np.arange(1000)}``). However, this syntax was deprecated,
-as Uproot will switch to writing RNTuples with syntax, since the HEP community is moving towards RNTuples.
+
+.. note::
+
+    Starting in v5.7.0, Uproot uses RNTuples as the default format for writing data when using the dict-like assignment syntax (e.g., ``file["my_data"] = {"my_array": np.arange(1000)}``). If you specifically want to write a TTree, you should use the :ref:`uproot.writing.writable.WritableDirectory.mktree` method.
 
 .. code-block:: python
 
@@ -1327,14 +1331,21 @@ Writing RNTuples
 
 Just like with reading, writing RNTuples is similar to writing TTree objects. Since RNTuples are much simpler, we aim to be able to write almost any RNTuple that you might want.
 
-Here is an example of writing an RNTuple. Since TTree is still the default format for the near future, writing an RNTuple is a bit more verbose.
+RNTuples are the default format for writing data starting in Uproot v5.7.0. You can write an RNTuple by using a dict-like syntax:
 
 .. code-block:: python
 
     >>> file = uproot.recreate("example.root")
     >>> data = {"my_int": [1,2], "my_vector": [[1,2], [3,4,5]]}
-    >>> rntuple = file.mkrntuple("my_rntuple", data)
-    >>> rntuple.extend(data) # Can be extended, just like TTrees
+    >>> file["my_rntuple"] = data
+    >>> file["my_rntuple"].extend(data) # Can be extended, just like TTrees
+
+You can also use the :ref:`uproot.writing.writable.WritableDirectory.mkrntuple` method for more explicit RNTuple creation, and to have the ability to initialize an empty RNTuple from a type specification dictionary or an Awkward form.
+
+.. code-block:: python
+
+    >>> file.mkrntuple("ntuple", {"x": "f4", "y": "var * int64"})
+    <WritableNTuple '/ntuple' at 0x000131ff30e0>
 
 Using your own interpretation
 --------------------------------

src/uproot/writing/writable.py

@@ -521,9 +521,11 @@ class WritableDirectory(MutableMapping):
     Subdirectories created this way will never be empty; to make an empty directory,
     use :ref:`uproot.writing.writable.WritableDirectory.mkdir`.
 
-    Similarly, non-empty TTrees can be created by assignment (see :doc:`uproot.writing.writable.WritableTree`
-    for recognized TTree-like data), but empty TTrees require the
-    :ref:`uproot.writing.writable.WritableDirectory.mktree` method.
+    Similarly, non-empty RNTuples can be created by assignment starting in Uproot
+    v5.7.0 (see :doc:`uproot.writing.writable.WritableNTuple` for recognized
+    RNTuple-like data), but empty RNTuples require the
+    :ref:`uproot.writing.writable.WritableDirectory.mkrntuple` method.
+    Writing a TTree requires the :ref:`uproot.writing.writable.WritableDirectory.mktree` method.
     """
 
     def __init__(self, path, file, cascading):
@@ -1285,15 +1287,9 @@ def mktree(
 
         Creates an empty TTree in this directory.
 
-        Note that TTrees can be created by assigning TTree-like data to a directory
-        (see :doc:`uproot.writing.writable.WritableTree` for recognized TTree-like types):
-
-        .. code-block:: python
-
-            my_directory["tree"] = {"branch1": np.array(...), "branch2": ak.Array(...)}
-
-        but TTrees created this way will never be empty. Use this method
-        to make an empty TTree or to control its parameters.
+        Note that starting in v5.7.0, Uproot uses RNTuples as the default format for writing
+        data when using the dict-like assignment syntax. Writing a TTree requires using this
+        method.
         """
         if self._file.sink.closed:
             raise ValueError("cannot create a TTree in a closed file")
@@ -1388,6 +1384,16 @@ def mkrntuple(
             description (str): Description for the new RNTuple.
 
         Creates an empty RNTuple in this directory.
+
+        Note that starting in v5.7.0, non-empty RNTuples can be created by
+        assigning RNTuple-like data to a directory:
+
+        .. code-block:: python
+
+            my_directory["ntuple"] = {"field1": np.array(...), "field2": ak.Array(...)}
+
+        but RNTuples created this way will never be empty. Use this method
+        to make an empty RNTuple or to control its parameters.
         """
         if self._file.sink.closed:
             raise ValueError("cannot create a RNTuple in a closed file")
@@ -2012,10 +2018,11 @@ class WritableNTuple:
 
     Represents a writable ``RNTuple`` from a ROOT file.
 
-    Assigning TTree-like data to a directory creates the TTree object with all of
-    its metadata and fills it with the contents of the arrays in one step. To separate
-    the process of creating the TTree metadata from filling the first TBasket, use the
-    :doc:`uproot.writing.writable.WritableDirectory.mktree` method:
+    Assigning data to a directory creates an RNTuple object by default starting in Uproot v5.7.0.
+    This creates the RNTuple object with all of its metadata and fills it with
+    the contents of the arrays in one step. To separate the process of creating the
+    RNTuple metadata from filling the first cluster, use the
+    :doc:`uproot.writing.writable.WritableDirectory.mkrntuple` method:
 
     .. code-block:: python
 
@@ -2039,8 +2046,8 @@ class WritableNTuple:
     and slow to read (especially for Uproot, but also for ROOT).
 
     For instance, if you want to write a million events and have enough memory
-    available to do that 100 thousand events at a time (total of 10 TBaskets),
-    then do so. Filling the RNTuple a hundred events at a time (total of 10000 TBaskets)
+    available to do that 100 thousand events at a time (total of 10 clusters),
+    then do so. Filling the RNTuple a hundred events at a time (total of 10000 clusters)
     would be considerably slower for writing and reading, and the file would be much
     larger than it could otherwise be, even with compression.
     """