You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@couchdb.apache.org by va...@apache.org on 2023/02/17 16:31:14 UTC
[couchdb] branch main updated: docs/api: use {params} consistently in titles (#4426)
This is an automated email from the ASF dual-hosted git repository.
vatamane pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/couchdb.git
The following commit(s) were added to refs/heads/main by this push:
new 9f8cf48e9 docs/api: use {params} consistently in titles (#4426)
9f8cf48e9 is described below
commit 9f8cf48e9ebd8cedf9ec393969b98e0b443d6749
Author: Alex Anderson <19...@users.noreply.github.com>
AuthorDate: Fri Feb 17 19:31:08 2023 +0300
docs/api: use {params} consistently in titles (#4426)
Use `{db}` and `{ddoc}` consistently in paths and titles
Authored-by: @alxndrsn
---
src/docs/src/api/database/bulk-api.rst | 4 ++--
src/docs/src/api/database/changes.rst | 6 +++---
src/docs/src/api/database/common.rst | 6 +++---
src/docs/src/api/database/compact.rst | 24 ++++++++++-----------
src/docs/src/api/database/find.rst | 14 ++++++------
src/docs/src/api/database/index.rst | 4 ++--
src/docs/src/api/database/misc.rst | 26 +++++++++++-----------
src/docs/src/api/database/security.rst | 6 +++---
src/docs/src/api/database/shard.rst | 14 ++++++------
src/docs/src/api/ddoc/common.rst | 18 ++++++++--------
src/docs/src/api/ddoc/render.rst | 36 +++++++++++++++----------------
src/docs/src/api/ddoc/rewrites.rst | 2 +-
src/docs/src/api/ddoc/search.rst | 12 +++++------
src/docs/src/api/ddoc/views.rst | 6 +++---
src/docs/src/api/document/attachments.rst | 6 +++---
src/docs/src/api/document/common.rst | 6 +++---
src/docs/src/api/local.rst | 24 +++++++++++----------
src/docs/src/api/partitioned-dbs.rst | 28 ++++++++++++------------
src/docs/src/whatsnew/0.11.rst | 2 +-
19 files changed, 123 insertions(+), 121 deletions(-)
diff --git a/src/docs/src/api/database/bulk-api.rst b/src/docs/src/api/database/bulk-api.rst
index 14e72ba7c..85b6302b2 100644
--- a/src/docs/src/api/database/bulk-api.rst
+++ b/src/docs/src/api/database/bulk-api.rst
@@ -442,8 +442,8 @@ Sending multiple queries to a database
}
.. Note::
- The multiple queries are also supported in /db/_local_docs/queries and
- /db/_design_docs/queries (similar to /db/_all_docs/queries).
+ The multiple queries are also supported in /{db}/_local_docs/queries and
+ /{db}/_design_docs/queries (similar to /{db}/_all_docs/queries).
.. _api/db/bulk_get:
diff --git a/src/docs/src/api/database/changes.rst b/src/docs/src/api/database/changes.rst
index 6c90bc3dc..ed4657bca 100644
--- a/src/docs/src/api/database/changes.rst
+++ b/src/docs/src/api/database/changes.rst
@@ -12,9 +12,9 @@
.. _api/db/changes:
-================
-``/db/_changes``
-================
+==================
+``/{db}/_changes``
+==================
.. http:get:: /{db}/_changes
:synopsis: Returns changes for the given database
diff --git a/src/docs/src/api/database/common.rst b/src/docs/src/api/database/common.rst
index 4831ab712..e6e81fb7d 100644
--- a/src/docs/src/api/database/common.rst
+++ b/src/docs/src/api/database/common.rst
@@ -12,9 +12,9 @@
.. _api/db:
-=======
-``/db``
-=======
+=========
+``/{db}``
+=========
.. http:head:: /{db}
:synopsis: Checks the database existence
diff --git a/src/docs/src/api/database/compact.rst b/src/docs/src/api/database/compact.rst
index 529718389..8d81d5023 100644
--- a/src/docs/src/api/database/compact.rst
+++ b/src/docs/src/api/database/compact.rst
@@ -12,9 +12,9 @@
.. _api/db/compact:
-================
-``/db/_compact``
-================
+==================
+``/{db}/_compact``
+==================
.. http:post:: /{db}/_compact
:synopsis: Starts a compaction for the database
@@ -82,9 +82,9 @@
.. _api/db/compact/ddoc:
-===========================
-``/db/_compact/design-doc``
-===========================
+=========================
+``/{db}/_compact/{ddoc}``
+=========================
.. http:post:: /{db}/_compact/{ddoc}
:synopsis: Starts a compaction for all the views in the selected
@@ -141,9 +141,9 @@
.. _api/db/ensure_full_commit:
-===========================
-``/db/_ensure_full_commit``
-===========================
+=============================
+``/{db}/_ensure_full_commit``
+=============================
.. http:post:: /{db}/_ensure_full_commit
:synopsis: Deprecated endpoint to support CouchDB versions < 3.0
@@ -196,9 +196,9 @@
.. _api/db/view_cleanup:
-=====================
-``/db/_view_cleanup``
-=====================
+=======================
+``/{db}/_view_cleanup``
+=======================
.. http:post:: /{db}/_view_cleanup
:synopsis: Removes view files that are not used by any design document
diff --git a/src/docs/src/api/database/find.rst b/src/docs/src/api/database/find.rst
index 0e511e6ad..b99267f39 100644
--- a/src/docs/src/api/database/find.rst
+++ b/src/docs/src/api/database/find.rst
@@ -13,7 +13,7 @@
.. _api/db/_find:
================
-``/db/_find``
+``/{db}/_find``
================
.. http:post:: /{db}/_find
@@ -946,7 +946,7 @@ The execution statistics currently include:
.. _api/db/find/index:
================
-``/db/_index``
+``/{db}/_index``
================
.. _api/db/find/index-post:
@@ -1166,7 +1166,7 @@ it easier to take advantage of future improvements to query planning
.. http:get:: /{db}/_index
:synopsis: List all indexes.
- When you make a ``GET`` request to ``/db/_index``, you get a list of all
+ When you make a ``GET`` request to ``/{db}/_index``, you get a list of all
indexes in the database. In addition to the information available through
this API, indexes are also stored in design documents <index-functions>.
Design documents are regular documents that have an ID starting with
@@ -1189,7 +1189,7 @@ it easier to take advantage of future improvements to query planning
Format of index objects:
- **ddoc**: ID of the design document the index belongs to. This ID
can be used to retrieve the design document containing the index,
- by making a ``GET`` request to ``/db/ddoc``, where ``ddoc`` is the
+ by making a ``GET`` request to ``/{db}/ddoc``, where ``ddoc`` is the
value of this field.
- **name**: Name of the index.
- **type**: Type of the index. Currently "json" is the only
@@ -1290,9 +1290,9 @@ it easier to take advantage of future improvements to query planning
.. _api/db/find/explain:
-================
-``/db/_explain``
-================
+==================
+``/{db}/_explain``
+==================
.. http:post:: /{db}/_explain
:synopsis: Identify which index is being used by a particular query.
diff --git a/src/docs/src/api/database/index.rst b/src/docs/src/api/database/index.rst
index 1fbce3ea5..c1cb45ecc 100644
--- a/src/docs/src/api/database/index.rst
+++ b/src/docs/src/api/database/index.rst
@@ -32,9 +32,9 @@ For clarity, the form below is used in the URL paths:
.. code-block:: none
- GET /db
+ GET /{db}
-Where ``db`` is the name of any database.
+Where ``{db}`` is the name of any database.
.. toctree::
common
diff --git a/src/docs/src/api/database/misc.rst b/src/docs/src/api/database/misc.rst
index 598f6e656..288b04871 100644
--- a/src/docs/src/api/database/misc.rst
+++ b/src/docs/src/api/database/misc.rst
@@ -12,9 +12,9 @@
.. _api/db/purge:
-==============
-``/db/_purge``
-==============
+================
+``/{db}/_purge``
+================
.. http:post:: /{db}/_purge
:synopsis: Purges documents entirely from database
@@ -178,7 +178,7 @@ following behavior:
.. _api/db/_purged_infos_limit:
==============================
-``/db/_purged_infos_limit``
+``/{db}/_purged_infos_limit``
==============================
.. http:get:: /{db}/_purged_infos_limit
@@ -274,9 +274,9 @@ following behavior:
.. _api/db/missing_revs:
-=====================
-``/db/_missing_revs``
-=====================
+=======================
+``/{db}/_missing_revs``
+=======================
.. http:post:: /{db}/_missing_revs
:synopsis: By given list of document revisions returns the document
@@ -335,9 +335,9 @@ following behavior:
.. _api/db/revs_diff:
-==================
-``/db/_revs_diff``
-==================
+====================
+``/{db}/_revs_diff``
+====================
.. http:post:: /{db}/_revs_diff
:synopsis: By given list of document revisions returns differences between
@@ -419,9 +419,9 @@ following behavior:
.. _api/db/revs_limit:
-===================
-``/db/_revs_limit``
-===================
+=====================
+``/{db}/_revs_limit``
+=====================
.. http:get:: /{db}/_revs_limit
:synopsis: Returns the limit of historical revisions to store for
diff --git a/src/docs/src/api/database/security.rst b/src/docs/src/api/database/security.rst
index 52ed7aad3..b90c832ce 100644
--- a/src/docs/src/api/database/security.rst
+++ b/src/docs/src/api/database/security.rst
@@ -12,9 +12,9 @@
.. _api/db/security:
-=================
-``/db/_security``
-=================
+===================
+``/{db}/_security``
+===================
.. http:get:: /{db}/_security
:synopsis: Returns the special security object for the database
diff --git a/src/docs/src/api/database/shard.rst b/src/docs/src/api/database/shard.rst
index 4abc4f0fd..1b923240d 100644
--- a/src/docs/src/api/database/shard.rst
+++ b/src/docs/src/api/database/shard.rst
@@ -12,9 +12,9 @@
.. _api/db/shards:
-===============
-``/db/_shards``
-===============
+=================
+``/{db}/_shards``
+=================
.. versionadded:: 2.0
@@ -105,7 +105,7 @@
.. _api/db/shards/doc:
==============================
-``/db/_shards/doc``
+``/{db}/_shards/{docid}``
==============================
.. http:get:: /{db}/_shards/{docid}
@@ -161,9 +161,9 @@
.. _api/db/sync_shards:
-=====================
-``/db/_sync_shards``
-=====================
+======================
+``/{db}/_sync_shards``
+======================
.. versionadded:: 2.3.1
diff --git a/src/docs/src/api/ddoc/common.rst b/src/docs/src/api/ddoc/common.rst
index 95aef4f47..53dbc584f 100644
--- a/src/docs/src/api/ddoc/common.rst
+++ b/src/docs/src/api/ddoc/common.rst
@@ -12,9 +12,9 @@
.. _api/ddoc:
-==========================
-``/db/_design/design-doc``
-==========================
+========================
+``/{db}/_design/{ddoc}``
+========================
.. http:head:: /{db}/_design/{ddoc}
:synopsis: Returns bare information in the HTTP Headers for
@@ -94,9 +94,9 @@
.. _api/ddoc/attachment:
-=====================================
-``/db/_design/design-doc/attachment``
-=====================================
+==================================
+``/{db}/_design/{ddoc}/{attname}``
+==================================
.. http:head:: /{db}/_design/{ddoc}/{attname}
:synopsis: Returns bare information in the HTTP Headers for the attachment
@@ -136,9 +136,9 @@
.. _api/ddoc/info:
-================================
-``/db/_design/design-doc/_info``
-================================
+==============================
+``/{db}/_design/{ddoc}/_info``
+==============================
.. http:get:: /{db}/_design/{ddoc}/_info
:synopsis: Returns view index information for the specified design document
diff --git a/src/docs/src/api/ddoc/render.rst b/src/docs/src/api/ddoc/render.rst
index d7c7b0ec9..676095185 100644
--- a/src/docs/src/api/ddoc/render.rst
+++ b/src/docs/src/api/ddoc/render.rst
@@ -12,9 +12,9 @@
.. _api/ddoc/show:
-==========================================
-``/db/_design/design-doc/_show/show-name``
-==========================================
+=====================================
+``/{db}/_design/{ddoc}/_show/{func}``
+=====================================
.. warning::
@@ -76,9 +76,9 @@
.. _api/ddoc/show/id:
-=================================================
-``/db/_design/design-doc/_show/show-name/doc-id``
-=================================================
+=============================================
+``/{db}/_design/{ddoc}/_show/{func}/{docid}``
+=============================================
.. warning::
@@ -141,9 +141,9 @@
.. _api/ddoc/list:
-====================================================
-``/db/_design/design-doc/_list/list-name/view-name``
-====================================================
+============================================
+``/{db}/_design/{ddoc}/_list/{func}/{view}``
+============================================
.. warning::
@@ -212,9 +212,9 @@
.. _api/ddoc/list/ddoc:
-===============================================================
-``/db/_design/design-doc/_list/list-name/other-ddoc/view-name``
-===============================================================
+=========================================================
+``/{db}/_design/{ddoc}/_list/{func}/{other-ddoc}/{view}``
+=========================================================
.. warning::
@@ -284,9 +284,9 @@
.. _api/ddoc/update:
-==============================================
-``/db/_design/design-doc/_update/update-name``
-==============================================
+=======================================
+``/{db}/_design/{ddoc}/_update/{func}``
+=======================================
.. http:post:: /{db}/_design/{ddoc}/_update/{func}
:synopsis: Executes an update function against the null document
@@ -348,9 +348,9 @@
.. _api/ddoc/update/id:
-=====================================================
-``/db/_design/design-doc/_update/update-name/doc-id``
-=====================================================
+===============================================
+``/{db}/_design/{ddoc}/_update/{func}/{docid}``
+===============================================
.. http:put:: /{db}/_design/{ddoc}/_update/{func}/{docid}
:synopsis: Executes an update function against the specified document
diff --git a/src/docs/src/api/ddoc/rewrites.rst b/src/docs/src/api/ddoc/rewrites.rst
index 5eb0f496e..e7a8711d6 100644
--- a/src/docs/src/api/ddoc/rewrites.rst
+++ b/src/docs/src/api/ddoc/rewrites.rst
@@ -13,7 +13,7 @@
.. _api/ddoc/rewrite:
========================================
-``/db/_design/design-doc/_rewrite/path``
+``/{db}/_design/{ddoc}/_rewrite/{path}``
========================================
.. warning::
diff --git a/src/docs/src/api/ddoc/search.rst b/src/docs/src/api/ddoc/search.rst
index 37b47a154..31bb1c096 100644
--- a/src/docs/src/api/ddoc/search.rst
+++ b/src/docs/src/api/ddoc/search.rst
@@ -12,9 +12,9 @@
.. _api/ddoc/search:
-=============================================
-``/db/_design/design-doc/_search/index-name``
-=============================================
+========================================
+``/{db}/_design/{ddoc}/_search/{index}``
+========================================
.. warning::
Search endpoints require a running search plugin connected to each cluster
@@ -124,9 +124,9 @@
For more information about how search works, see the
:ref:`Search User Guide<ddoc/search>`.
-==================================================
-``/db/_design/design-doc/_search_info/index-name``
-==================================================
+=============================================
+``/{db}/_design/{ddoc}/_search_info/{index}``
+=============================================
.. warning::
Search endpoints require a running search plugin connected to each cluster
diff --git a/src/docs/src/api/ddoc/views.rst b/src/docs/src/api/ddoc/views.rst
index 7cb6af852..6205c6b86 100644
--- a/src/docs/src/api/ddoc/views.rst
+++ b/src/docs/src/api/ddoc/views.rst
@@ -12,9 +12,9 @@
.. _api/ddoc/view:
-==========================================
-``/db/_design/design-doc/_view/view-name``
-==========================================
+=====================================
+``/{db}/_design/{ddoc}/_view/{view}``
+=====================================
.. http:get:: /{db}/_design/{ddoc}/_view/{view}
:synopsis: Returns results for the specified stored view
diff --git a/src/docs/src/api/document/attachments.rst b/src/docs/src/api/document/attachments.rst
index 8baf07e91..d6bedd5fe 100644
--- a/src/docs/src/api/document/attachments.rst
+++ b/src/docs/src/api/document/attachments.rst
@@ -12,9 +12,9 @@
.. _api/doc/attachment:
-======================
-``/db/doc/attachment``
-======================
+===========================
+``/{db}/{docid}/{attname}``
+===========================
.. http:head:: /{db}/{docid}/{attname}
:synopsis: Returns bare information in the HTTP Headers for the attachment
diff --git a/src/docs/src/api/document/common.rst b/src/docs/src/api/document/common.rst
index 03ea29064..4887d45c6 100644
--- a/src/docs/src/api/document/common.rst
+++ b/src/docs/src/api/document/common.rst
@@ -12,9 +12,9 @@
.. _api/doc:
-===========
-``/db/doc``
-===========
+=================
+``/{db}/{docid}``
+=================
.. http:head:: /{db}/{docid}
:synopsis: Returns bare information in the HTTP Headers for the document
diff --git a/src/docs/src/api/local.rst b/src/docs/src/api/local.rst
index 0fa78a4d7..6301117a6 100644
--- a/src/docs/src/api/local.rst
+++ b/src/docs/src/api/local.rst
@@ -27,7 +27,7 @@ Local documents have the following limitations:
- Local documents are not output by views, or the :ref:`api/db/all_docs` view.
-From CouchDB 2.0, Local documents can be listed by using the /db/_local_docs
+From CouchDB 2.0, Local documents can be listed by using the :ref:`api/db/_local_docs`
endpoint.
Local documents can be used when you want to store configuration or
@@ -38,24 +38,24 @@ A list of the available methods and URL paths are provided below:
+--------+------------------------+--------------------------------------------+
| Method | Path | Description |
+========+========================+============================================+
-| GET, | /db/_local_docs | Returns a list of all the |
+| GET, | /{db}/_local_docs | Returns a list of all the |
| POST | | non-replicated documents in the database |
+--------+------------------------+--------------------------------------------+
-| GET | /db/_local/id | Returns the latest revision of the |
+| GET | /{db}/_local/{docid} | Returns the latest revision of the |
| | | non-replicated document |
+--------+------------------------+--------------------------------------------+
-| PUT | /db/_local/id | Inserts a new version of the |
+| PUT | /{db}/_local/{docid} | Inserts a new version of the |
| | | non-replicated document |
+--------+------------------------+--------------------------------------------+
-| DELETE | /db/_local/id | Deletes the non-replicated document |
+| DELETE | /{db}/_local/{docid} | Deletes the non-replicated document |
+--------+------------------------+--------------------------------------------+
-| COPY | /db/_local/id | Copies the non-replicated document |
+| COPY | /{db}/_local/{docid} | Copies the non-replicated document |
+--------+------------------------+--------------------------------------------+
-.. _api/local/doc:
+.. _api/db/_local_docs:
-``/db/_local_docs``
-===================
+``/{db}/_local_docs``
+=====================
.. http:get:: /{db}/_local_docs
:synopsis: Returns a built-in view of all local (non-replicating) documents
@@ -223,8 +223,10 @@ A list of the available methods and URL paths are provided below:
"offset" : null
}
-``/db/_local/id``
-=================
+.. _api/db/_local/doc:
+
+``/{db}/_local/{docid}``
+========================
.. http:get:: /{db}/_local/{docid}
:synopsis: Returns the latest revision of the local document
diff --git a/src/docs/src/api/partitioned-dbs.rst b/src/docs/src/api/partitioned-dbs.rst
index e5ec55e83..1a280140f 100644
--- a/src/docs/src/api/partitioned-dbs.rst
+++ b/src/docs/src/api/partitioned-dbs.rst
@@ -23,10 +23,10 @@ partition.
See the guide for
:ref:`getting started with partitioned databases <partitioned-dbs>`
-``/db/_partition/partition``
-============================
+``/{db}/_partition/{partition_id}``
+===================================
-.. http:get:: /{db}/_partition/{partition}
+.. http:get:: /{db}/_partition/{partition_id}
:synopsis: Returns document and size info for the given partition
This endpoint returns information describing the provided partition.
@@ -65,14 +65,14 @@ See the guide for
}
}
-``/db/_partition/partition/_all_docs``
-======================================
+``/{db}/_partition/{partition_id}/_all_docs``
+=============================================
-.. http:get:: /{db}/_partition/{partition}/_all_docs
+.. http:get:: /{db}/_partition/{partition_id}/_all_docs
:synopsis: Return all docs in the specified partition
:param db: Database name
- :param partition: Partition name
+ :param partition_id: Partition name
This endpoint is a convenience endpoint for automatically setting
bounds on the provided partition range. Similar results can be had
@@ -119,14 +119,14 @@ See the guide for
.. _api/partitioned/views:
-``/db/_partition/partition/_design/design-doc/_view/view-name``
+``/{db}/_partition/{partition_id}/_design/{ddoc}/_view/{view}``
===============================================================
-.. http:get:: /{db}/_partition/{partition}/_design/{ddoc}/_view/{view}
+.. http:get:: /{db}/_partition/{partition_id}/_design/{ddoc}/_view/{view}
:synopsis: Execute a partitioned query
:param db: Database name
- :param partition: Partition name
+ :param partition_id: Partition name
:param ddoc: Design document id
:param view: View name
@@ -196,8 +196,8 @@ See the guide for
}
.. _api/partitioned/find:
-``/db/_partition/partition_id/_find``
-=====================================
+``/{db}/_partition/{partition_id}/_find``
+=========================================
.. http:post:: /{db}/_partition/{partition_id}/_find
:synopsis: Query the partition specified by ``partition_id``
@@ -215,8 +215,8 @@ See the guide for
of the returned data.
.. _api/partitioned/explain:
-``/db/_partition/partition_id/_explain``
-========================================
+``/{db}/_partition/{partition_id}/_explain``
+============================================
.. http:post:: /{db}/_partition/{partition_id}/_explain
:synopsis: Find index that is used with a query
diff --git a/src/docs/src/whatsnew/0.11.rst b/src/docs/src/whatsnew/0.11.rst
index 854ab88f3..e861ffb09 100644
--- a/src/docs/src/whatsnew/0.11.rst
+++ b/src/docs/src/whatsnew/0.11.rst
@@ -58,7 +58,7 @@ _admins -> _security
^^^^^^^^^^^^^^^^^^^^
The `/db/_admins` handler has been removed and replaced with a
-:ref:`/db/_security <api/db/security>` object. Any existing `_admins` will be
+:ref:`/{db}/_security <api/db/security>` object. Any existing `_admins` will be
dropped and need to be added to the security object again. The reason for this
is that the old system made no distinction between names and roles, while the
new one does, so there is no way to automatically upgrade the old admins list.