20840: Add warning boxes to legacy APIs and rearrange API listing

Arvados-DCO-1.1-Signed-off-by: Peter Amstutz <peter.amstutz@curii.com>

diff --git a/doc/_config.yml b/doc/_config.yml
index b42a3c8b956d0b2a270faa3f6e15c85dd6ab1613..cbb082aefb642ab02bec901cdd27f74310b04e73 100644 (file)
--- a/doc/_config.yml
+++ b/doc/_config.yml
@@ -109,19 +109,14 @@ navbar:
       - api/methods.html.textile.liquid
       - api/resources.html.textile.liquid
     - Permission and authentication:
+      - api/methods/users.html.textile.liquid
+      - api/methods/groups.html.textile.liquid
       - api/methods/api_client_authorizations.html.textile.liquid
-      - api/methods/api_clients.html.textile.liquid
+      - api/methods/links.html.textile.liquid
       - api/methods/authorized_keys.html.textile.liquid
-      - api/methods/groups.html.textile.liquid
-      - api/methods/users.html.textile.liquid
+      - api/methods/api_clients.html.textile.liquid
       - api/methods/user_agreements.html.textile.liquid
-    - System resources:
-      - api/methods/keep_services.html.textile.liquid
-      - api/methods/links.html.textile.liquid
-      - api/methods/logs.html.textile.liquid
-      - api/methods/nodes.html.textile.liquid
       - api/methods/virtual_machines.html.textile.liquid
-      - api/methods/keep_disks.html.textile.liquid
     - Data management:
       - api/keep-webdav.html.textile.liquid
       - api/keep-s3.html.textile.liquid
@@ -129,12 +124,12 @@ navbar:
       - api/projects.html.textile.liquid
       - api/properties.html.textile.liquid
       - api/methods/collections.html.textile.liquid
-      - api/methods/repositories.html.textile.liquid
+      - api/methods/logs.html.textile.liquid
+      - api/methods/keep_services.html.textile.liquid
     - Container engine:
       - api/methods/container_requests.html.textile.liquid
       - api/methods/containers.html.textile.liquid
       - api/methods/workflows.html.textile.liquid
-    - Management (admin/system):
       - api/dispatch.html.textile.liquid
     - Jobs engine (legacy):
       - api/crunch-scripts.html.textile.liquid
@@ -142,7 +137,10 @@ navbar:
       - api/methods/job_tasks.html.textile.liquid
       - api/methods/pipeline_instances.html.textile.liquid
       - api/methods/pipeline_templates.html.textile.liquid
-    - Metadata for bioinformatics (deprecated):
+      - api/methods/nodes.html.textile.liquid
+      - api/methods/repositories.html.textile.liquid
+      - api/methods/keep_disks.html.textile.liquid
+    - Metadata for bioinformatics (legacy):
       - api/methods/humans.html.textile.liquid
       - api/methods/specimens.html.textile.liquid
       - api/methods/traits.html.textile.liquid

diff --git a/doc/api/crunch-scripts.html.textile.liquid b/doc/api/crunch-scripts.html.textile.liquid
index 3d6ccbdd5b8ac5d25411e60a5e0b6a1591bc53d7..5d7fe5d98fa9104da43c7ca72a9d73977367c6f1 100644 (file)
--- a/doc/api/crunch-scripts.html.textile.liquid
+++ b/doc/api/crunch-scripts.html.textile.liquid
@@ -11,7 +11,9 @@ Copyright (C) The Arvados Authors. All rights reserved.
 SPDX-License-Identifier: CC-BY-SA-3.0
 {% endcomment %}
 
-p=. *Legacy.  The job APIs are read-only and disabled by default in new installations.  Use "container requests":methods/container_requests.html .*
+{% include 'notebox_begin_warning' %}
+This is a legacy API.  This endpoint is deprecated, disabled by default in new installations, and is slated to be removed entirely in a future major release of Arvados.  Is is replaced by "container requests.":methods/container_requests.html
+{% include 'notebox_end' %}
 
 h2. Crunch scripts
 

diff --git a/doc/api/methods/api_client_authorizations.html.textile.liquid b/doc/api/methods/api_client_authorizations.html.textile.liquid
index bcf77564c5e793f12646fca760cf22dd9c575640..597760bb90668c215c26852fee911800924ebd12 100644 (file)
--- a/doc/api/methods/api_client_authorizations.html.textile.liquid
+++ b/doc/api/methods/api_client_authorizations.html.textile.liquid
@@ -27,8 +27,6 @@ table(table table-bordered table-condensed).
 |_. Attribute|_. Type|_. Description|_. Example|
 |uuid|string|An identifier used to refer to the token without exposing the actual token.||
 |api_token|string|The actual token string that is expected in the Authorization header.||
-|api_client_id|integer|-||
-|user_id|integer|-||
 |created_by_ip_address|string|-||
 |last_used_by_ip_address|string|The network address of the most recent client using this token.||
 |last_used_at|datetime|Timestamp of the most recent request using this token.||

diff --git a/doc/api/methods/collections.html.textile.liquid b/doc/api/methods/collections.html.textile.liquid
index 5871337b0ae8b14760d9d32292a27f1eed29ecc8..29d28d42a221cd95e6436a1e2c61a6eb173cb2aa 100644 (file)
--- a/doc/api/methods/collections.html.textile.liquid
+++ b/doc/api/methods/collections.html.textile.liquid
@@ -19,7 +19,7 @@ Example UUID: @zzzzz-4zz18-0123456789abcde@
 
 h2. Resource
 
-Collections describe sets of files in terms of data blocks stored in Keep.  See "Keep - Content-Addressable Storage":{{site.baseurl}}/architecture/storage.html for details.
+Collections describe sets of files in terms of data blocks stored in Keep.  See "Keep - Content-Addressable Storage":{{site.baseurl}}/architecture/storage.html and "using collection versioning":../../user/topics/collection-versioning.html for details.
 
 Each collection has, in addition to the "Common resource fields":{{site.baseurl}}/api/resources.html:
 

diff --git a/doc/api/methods/humans.html.textile.liquid b/doc/api/methods/humans.html.textile.liquid
index e08e941cf66f68a21c0d6b765f09ddbec6faab11..1c338217eb8b0673a021457532038bf7c9ecbc34 100644 (file)
--- a/doc/api/methods/humans.html.textile.liquid
+++ b/doc/api/methods/humans.html.textile.liquid
@@ -11,7 +11,9 @@ Copyright (C) The Arvados Authors. All rights reserved.
 SPDX-License-Identifier: CC-BY-SA-3.0
 {% endcomment %}
 
-p=. *Deprecated, likely to be removed in a future version.  The recommended way to store metadata is "collection properties":collections.html*
+{% include 'notebox_begin_warning' %}
+This is a legacy API.  This endpoint is deprecated, disabled by default in new installations, and is slated to be removed entirely in a future major release of Arvados.  The recommended way to store metadata is with "'properties' field on collections and projects.":../properties.html
+{% include 'notebox_end' %}
 
 API endpoint base: @https://{{ site.arvados_api_host }}/arvados/v1/humans@
 

diff --git a/doc/api/methods/job_tasks.html.textile.liquid b/doc/api/methods/job_tasks.html.textile.liquid
index 69c3f07e3006a29ae3f64f7d6540aaf95343561d..2700708d6e5833891d8c15d0be77888d7fe84337 100644 (file)
--- a/doc/api/methods/job_tasks.html.textile.liquid
+++ b/doc/api/methods/job_tasks.html.textile.liquid
@@ -11,7 +11,9 @@ Copyright (C) The Arvados Authors. All rights reserved.
 SPDX-License-Identifier: CC-BY-SA-3.0
 {% endcomment %}
 
-p=. *Legacy.  This endpoint is read-only and disabled by default in new installations.*
+{% include 'notebox_begin_warning' %}
+This is a legacy API.  This endpoint is deprecated, disabled by default in new installations, and is slated to be removed entirely in a future major release of Arvados.  Is is replaced by "container requests.":container_requests.html
+{% include 'notebox_end' %}
 
 API endpoint base: @https://{{ site.arvados_api_host }}/arvados/v1/job_tasks@
 

diff --git a/doc/api/methods/jobs.html.textile.liquid b/doc/api/methods/jobs.html.textile.liquid
index aa7a58898a58dcb998f0de202db907a97843e5bf..3b806200c9eecc857b1df4cec1ea55139b7ee44d 100644 (file)
--- a/doc/api/methods/jobs.html.textile.liquid
+++ b/doc/api/methods/jobs.html.textile.liquid
@@ -11,7 +11,9 @@ Copyright (C) The Arvados Authors. All rights reserved.
 SPDX-License-Identifier: CC-BY-SA-3.0
 {% endcomment %}
 
-p=. *Legacy.  This endpoint is read-only and disabled by default in new installations.*
+{% include 'notebox_begin_warning' %}
+This is a legacy API.  This endpoint is deprecated, disabled by default in new installations, and is slated to be removed entirely in a future major release of Arvados.  Is is replaced by "container requests.":container_requests.html
+{% include 'notebox_end' %}
 
 API endpoint base: @https://{{ site.arvados_api_host }}/arvados/v1/jobs@
 

diff --git a/doc/api/methods/keep_disks.html.textile.liquid b/doc/api/methods/keep_disks.html.textile.liquid
index 7624b6699f9874559edbe77e31f03cc8b67d313f..f35ff80ad3a808779cb5e482964f6ed389e3e251 100644 (file)
--- a/doc/api/methods/keep_disks.html.textile.liquid
+++ b/doc/api/methods/keep_disks.html.textile.liquid
@@ -2,7 +2,7 @@
 layout: default
 navsection: api
 navmenu: API Methods
-title: "keep_disks (deprecated)"
+title: "keep_disks"
 
 ...
 {% comment %}
@@ -11,6 +11,10 @@ Copyright (C) The Arvados Authors. All rights reserved.
 SPDX-License-Identifier: CC-BY-SA-3.0
 {% endcomment %}
 
+{% include 'notebox_begin_warning' %}
+This is a legacy API.  This endpoint is deprecated, disabled by default in new installations, and is slated to be removed entirely in a future major release of Arvados.  Is is replaced by "keep services.":keep_services.html
+{% include 'notebox_end' %}
+
 API endpoint base: @https://{{ site.arvados_api_host }}/arvados/v1/keep_disks@
 
 Object type: @penuu@

diff --git a/doc/api/methods/nodes.html.textile.liquid b/doc/api/methods/nodes.html.textile.liquid
index 7ddc62519c1922ad48a254827078f7b0651065ea..40c9d0dfe053537e7ee9e911e3c35d063d90c8df 100644 (file)
--- a/doc/api/methods/nodes.html.textile.liquid
+++ b/doc/api/methods/nodes.html.textile.liquid
@@ -11,6 +11,10 @@ Copyright (C) The Arvados Authors. All rights reserved.
 SPDX-License-Identifier: CC-BY-SA-3.0
 {% endcomment %}
 
+{% include 'notebox_begin_warning' %}
+This is a legacy API.  This endpoint is deprecated, disabled by default in new installations, and is slated to be removed entirely in a future major release of Arvados.  Is is replaced by "cloud dispatcher API.":dispatch.html
+{% include 'notebox_end' %}
+
 API endpoint base: @https://{{ site.arvados_api_host }}/arvados/v1/nodes@
 
 Object type: @7ekkf@

diff --git a/doc/api/methods/pipeline_instances.html.textile.liquid b/doc/api/methods/pipeline_instances.html.textile.liquid
index 55baee9b5ab248d7f270eb3ff10d908270a48131..889056c146305d68c899bc2a23fa442bc9fd99fe 100644 (file)
--- a/doc/api/methods/pipeline_instances.html.textile.liquid
+++ b/doc/api/methods/pipeline_instances.html.textile.liquid
@@ -11,7 +11,9 @@ Copyright (C) The Arvados Authors. All rights reserved.
 SPDX-License-Identifier: CC-BY-SA-3.0
 {% endcomment %}
 
-p=. *Legacy.  This endpoint is read-only and disabled by default in new installations.*
+{% include 'notebox_begin_warning' %}
+This is a legacy API.  This endpoint is deprecated, disabled by default in new installations, and is slated to be removed entirely in a future major release of Arvados.  Is is replaced by "container requests.":container_requests.html
+{% include 'notebox_end' %}
 
 API endpoint base: @https://{{ site.arvados_api_host }}/arvados/v1/pipeline_instances@
 

diff --git a/doc/api/methods/pipeline_templates.html.textile.liquid b/doc/api/methods/pipeline_templates.html.textile.liquid
index 141072c51c451770830a9d22bd0fdd4185a826d9..8d2d0cd7b1027e0eafd886bddb32448cc8eafdb3 100644 (file)
--- a/doc/api/methods/pipeline_templates.html.textile.liquid
+++ b/doc/api/methods/pipeline_templates.html.textile.liquid
@@ -11,7 +11,9 @@ Copyright (C) The Arvados Authors. All rights reserved.
 SPDX-License-Identifier: CC-BY-SA-3.0
 {% endcomment %}
 
-p=. *Legacy.  This endpoint is read-only and disabled by default in new installations.*
+{% include 'notebox_begin_warning' %}
+This is a legacy API.  This endpoint is deprecated, disabled by default in new installations, and is slated to be removed entirely in a future major release of Arvados.  Is is replaced by "registered workflows.":workflows.html
+{% include 'notebox_end' %}
 
 API endpoint base: @https://{{ site.arvados_api_host }}/arvados/v1/pipeline_templates@
 

diff --git a/doc/api/methods/repositories.html.textile.liquid b/doc/api/methods/repositories.html.textile.liquid
index 7a47da6a3b27824247de24b5876c11cecb066b5c..3bef8bd4896d1802552edb1d7f4f935f429bb194 100644 (file)
--- a/doc/api/methods/repositories.html.textile.liquid
+++ b/doc/api/methods/repositories.html.textile.liquid
@@ -11,6 +11,10 @@ Copyright (C) The Arvados Authors. All rights reserved.
 SPDX-License-Identifier: CC-BY-SA-3.0
 {% endcomment %}
 
+{% include 'notebox_begin_warning' %}
+This is a legacy API.  This endpoint is deprecated, disabled by default in new installations, and is slated to be removed entirely in a future major release of Arvados.  Is is replaced by "collection versioning.":collections.html
+{% include 'notebox_end' %}
+
 API endpoint base: @https://{{ site.arvados_api_host }}/arvados/v1/repositories@
 
 Object type: @s0uqq@

diff --git a/doc/api/methods/specimens.html.textile.liquid b/doc/api/methods/specimens.html.textile.liquid
index be3712a2064cdd174150769078ccf5eaf5c5d8a6..3820eeb242b9125e3b3a9320af03e4043227edf2 100644 (file)
--- a/doc/api/methods/specimens.html.textile.liquid
+++ b/doc/api/methods/specimens.html.textile.liquid
@@ -10,7 +10,9 @@ Copyright (C) The Arvados Authors. All rights reserved.
 SPDX-License-Identifier: CC-BY-SA-3.0
 {% endcomment %}
 
-p=. *Deprecated, likely to be removed in a future version.  The recommended way to store metadata is "collection properties":collections.html*
+{% include 'notebox_begin_warning' %}
+This is a legacy API.  This endpoint is deprecated, disabled by default in new installations, and is slated to be removed entirely in a future major release of Arvados.  The recommended way to store metadata is with "'properties' field on collections and projects.":../properties.html
+{% include 'notebox_end' %}
 
 API endpoint base: @https://{{ site.arvados_api_host }}/arvados/v1/specimens@
 

diff --git a/doc/api/methods/traits.html.textile.liquid b/doc/api/methods/traits.html.textile.liquid
index e48804702eac9fd330d2431cf8e189a01188357d..4e356b95234e1d1bd8b21481c4d8d2d97825ecc3 100644 (file)
--- a/doc/api/methods/traits.html.textile.liquid
+++ b/doc/api/methods/traits.html.textile.liquid
@@ -11,7 +11,9 @@ Copyright (C) The Arvados Authors. All rights reserved.
 SPDX-License-Identifier: CC-BY-SA-3.0
 {% endcomment %}
 
-p=. *Deprecated, likely to be removed in a future version.  The recommended way to store metadata is "collection properties":collections.html*
+{% include 'notebox_begin_warning' %}
+This is a legacy API.  This endpoint is deprecated, disabled by default in new installations, and is slated to be removed entirely in a future major release of Arvados.  The recommended way to store metadata is with "'properties' field on collections and projects.":../properties.html
+{% include 'notebox_end' %}
 
 API endpoint base: @https://{{ site.arvados_api_host }}/arvados/v1/traits@