docs/getting-started: Update according to latest changes

Related T1650
Related T1648

docs/getting-started.rst

@@ -36,43 +36,7 @@ Prepare a deposit
          following compression algorithm gzip (`.tar.gz`, `.tgz`), bzip2
          (`.tar.bz2`) , or lzma (`.tar.lzma`)
 
-* prepare a metadata file (`more details <./metadata.html>`__.):
-
-  - specify metadata schema/vocabulary (CodeMeta is strongly recommended)
-  - specify *MUST* metadata (url, authors, software name and
-    the external\_identifier)
-  - add all available information under the compatible metadata term.
-
-  Here is an example of an atom entry file with CodeMeta terms:
-
-.. code:: xml
-
-  <?xml version="1.0" encoding="utf-8"?>
-  <entry xmlns="http://www.w3.org/2005/Atom"
-  xmlns:codemeta="https://doi.org/10.5063/SCHEMA/CODEMETA-2.0">
-    <title>Je suis GPL</title>
-    <client>swh</client>
-    <external_identifier>je-suis-gpl</external_identifier>
-    <codemeta:url>https://forge.softwareheritage.org/source/jesuisgpl/</codemeta:url>
-    <codemeta:dateCreated>2018-01-05</codemeta:dateCreated>
-    <codemeta:description>Je suis GPL is a modified version of GNU Hello whose
-      sole purpose is to showcase the usage of
-      Software Heritage for license compliance purposes.</codemeta:description>
-    <codemeta:version>0.1</codemeta:version>
-    <codemeta:runtimePlatform>GNU/Linux</codemeta:runtimePlatform>
-    <codemeta:developmentStatus>stable</codemeta:developmentStatus>
-    <codemeta:programmingLanguage>C</codemeta:programmingLanguage>
-
-    <codemeta:license>
-      <codemeta:name>GNU General Public License v3.0 or later</codemeta:name>
-      <codemeta:url>https://spdx.org/licenses/GPL-3.0-or-later.html</codemeta:url>
-    </codemeta:license>
-    <codemeta:author>
-      <codemeta:name>Stefano Zacchiroli</codemeta:name>
-      <codemeta:jobTitle>Maintainer</codemeta:jobTitle>
-    </codemeta:author>
-  </entry>
-
+* (Optional) prepare a metadata file (more details :ref:`deposit-metadata`):
 
 
 Push deposit
@@ -105,13 +69,17 @@ in one shot, sending exactly one POST query:
 For this, we need to provide the:
 
 * arguments: ``--username 'name' --password 'pass'`` as credentials
-* archive's path (example: ``--archive path/to/archive-name.tgz``) :
+* archive's path (example: ``--archive path/to/archive-name.tgz``)
+* software's name (optional if a metadata filepath is specified and the
+  artifact's name is included in the metadata file).
+* author's name (optional if a metadata filepath is specified and the authors
+  are included in the metadata file). This can be specified multiple times in
+  case of multiple authors.
 * (optionally) metadata file's path ``--metadata
-  path/to/file.metadata.xml``. If not provided, the archive's filename
-  will be used to determine the metadata file, e.g:
-  ``path/to/archive-name.tgz.metadata.xml``
-* (optionally) ``--slug 'your-id'`` argument, a reference to a
-  unique identifier the client uses for the software object.
+  path/to/file.metadata.xml``.
+* (optionally) ``--slug 'your-id'`` argument, a reference to a unique identifier
+  the client uses for the software object. If not provided, A UUID will be
+  generated by SWH.
 
 You can do this with the following command:
 
@@ -120,6 +88,8 @@ minimal deposit
 .. code:: shell
 
  $ swh deposit upload --username name --password secret \
+                      --author "some@noone" --author "second@noone" \
+                      --name 'je-suis-gpl' \
                       --archive je-suis-gpl.tgz
 
 with client's external identifier (``slug``)
@@ -127,6 +97,8 @@ with client's external identifier (``slug``)
 .. code:: shell
 
  $ swh deposit upload --username name --password secret \
+                      --author "some@noone" \
+                      --name 'je-suis-gpl' \
                       --archive je-suis-gpl.tgz \
                       --slug je-suis-gpl
 
@@ -135,11 +107,12 @@ to a specific client's collection
 .. code:: shell
 
  $ swh deposit upload --username name --password secret \
+                      --author "some@noone" \
+                      --name 'je-suis-gpl' \
                       --archive je-suis-gpl.tgz \
                       --collection 'second-collection'
 
 
-
 You just posted a deposit to your collection on Software Heritage
 
 
@@ -195,6 +168,8 @@ Continue the deposit by using the ``--deposit-id`` argument given as a response
 for the first step. You can continue adding content or metadata while you use
 the ``--partial`` argument.
 
+To only add one new archive to the deposit:
+
 .. code:: shell
 
   $ swh deposit upload --username name --password secret \
@@ -202,39 +177,30 @@ the ``--partial`` argument.
                        --deposit-id 42 \
                        --partial
 
-
-In case you want to add only one new archive without metadata:
+To only add metadata to the deposit:
 
 .. code:: shell
 
   $ swh deposit upload --username name --password secret \
-                       --archive add-foo.tar.gz \
-                       --archive-deposit \
+                       --metadata add-foo.tar.gz.metadata.xml \
                        --deposit-id 42 \
                        --partial
 
-If you want to add only metadata, use:
-
+or:
 .. code:: shell
 
   $ swh deposit upload --username name --password secret \
-                       --metadata add-foo.tar.gz.metadata.xml \
-                       --metadata-deposit \
+                       --name 'add-foo' --author 'someone' \
                        --deposit-id 42 \
                        --partial
 
+
 3. Finalize deposit
 ~~~~~~~~~~~~~~~~~~~
-On your last addition, by not declaring it as ``--partial``, the
-deposit will be considered as completed and its status will be changed
-to ``deposited``:
-
-.. code:: shell
 
-  $ swh deposit upload --username name --password secret \
-                       --metadata add-foo.tar.gz.metadata.xml \
-                       --metadata-deposit \
-                       --deposit-id 42
+On your last addition (same command as before), by not declaring it
+``--partial``, the deposit will be considered completed. Its status will be
+changed to ``deposited``
 
 
 Update deposit

docs/metadata.rst

+.. _deposit-metadata:
+
 Deposit metadata
 ================