From 7b8c32b19a4fbf969216638461eec2dfc554f749 Mon Sep 17 00:00:00 2001 From: Bob Grabar Date: Mon, 10 Sep 2012 12:38:37 -0400 Subject: [PATCH 1/4] DOCS-487 updated Sharding sign-post --- source/reference/commands.txt | 2 ++ source/replication.txt | 6 ++-- source/sharding.txt | 67 ++++++++++++++++++++--------------- 3 files changed, 45 insertions(+), 30 deletions(-) diff --git a/source/reference/commands.txt b/source/reference/commands.txt index 4fea3fd361d..efcd7af7279 100644 --- a/source/reference/commands.txt +++ b/source/reference/commands.txt @@ -79,6 +79,8 @@ shell helpers. User Commands ------------- +.. _sharding-commands: + Sharding ~~~~~~~~ diff --git a/source/replication.txt b/source/replication.txt index 402b4893a9c..5bb120ba036 100644 --- a/source/replication.txt +++ b/source/replication.txt @@ -5,7 +5,8 @@ Replication Database replication ensures redundancy, backup, and automatic failover. Replication occurs through groups of servers known as replica sets. -This page lists the documents, tutorials, and reference pages that describe replica sets. +This page lists the documents, tutorials, and reference pages that +describe replica sets. For an overview, see :doc:`/core/replication`. To work with members, see :doc:`administration/replica-sets`. To configure deployment @@ -28,13 +29,14 @@ The following is the expanded outline of the main documentation: applications/replication core/replication-internals +.. index:: tutorials; replica sets .. _replica-set-tutorials-list: Tutorials --------- The following tutorials describe certain replica set maintenance -operations in detail. +operations in detail: .. toctree:: :maxdepth: 1 diff --git a/source/sharding.txt b/source/sharding.txt index b1e1a8b2fea..f2df8075afc 100644 --- a/source/sharding.txt +++ b/source/sharding.txt @@ -2,43 +2,41 @@ Sharding ======== -.. index:: background; sharding +.. This was the only sign-post page with an index entry at the top, and +.. the entry seemed unlikely to be used. I've removed it. For top-level +.. pages, we have the left column. -bg + .. _sharding-background: -MongoDB provides an automatic sharding feature that distributes a -single logical database system across a cluster of machines. MongoDB +Sharding distributes a +single logical database system across a cluster of machines. Sharding uses range-based portioning to distribute :term:`documents ` -in a single collection between members of a shard cluster based on a -specific ":term:`shard key`. - -For a high-level introduction to the underlying concepts and operation -of sharding, consider ":doc:`/core/sharding`." To understand how -sharding works and to use sharding in your deployment, to read -":doc:`/administration/sharding-architectures`" document provides an -overview of basic system architectures. - -Administrators of shard clusters should also read the -":doc:`/administration/sharding`" document. This resource contains a -catalog of procedures for configuring and maintaining shard clusters, -in addition to a :ref:`troubleshooting ` -section to aid in diagnosing common issues with sharding. Use the -:ref:`sharding tutorials ` for instructions on -complete administrative operations. - -Finally, for details on MongoDB's internal operation of sharding, the -":doc:`/core/sharding-internals`" document addresses these underlying -concepts. +based on a +specific :term:`shard key`. + +This page lists the documents, tutorials, and reference pages that +describe sharding. + +For an overview, see :doc:`/core/sharding`. To configure, maintain, and +troubleshoot shard clusters, see :doc:`/administration/sharding`. For +deployment architectures, see +:doc:`/administration/sharding-architectures` For details on the +internal operations of sharding, see :doc:`/core/sharding-internals`. +For common procedures, see the :ref:`tutorials list +`. Documentation ------------- +The following is the expanded outline of the main documentation: + .. toctree:: :maxdepth: 3 core/sharding - core/sharding-internals administration/sharding administration/sharding-architectures + core/sharding-internals .. index:: tutorials; sharding .. _sharding-tutorials: @@ -46,7 +44,7 @@ Documentation Tutorials --------- -The following tutorials outline basic administrative process for +The following tutorials describe basic administrative procedures for deploying and managing shard clusters: .. toctree:: @@ -56,9 +54,22 @@ deploying and managing shard clusters: tutorial/add-shards-to-shard-cluster tutorial/remove-shards-from-cluster -Additionally, the :doc:`/tutorial/enforce-unique-keys-for-sharded-collections` -tutorial describes a sharding-specific application development -pattern. +The following tutorial describes a sharding-specific application +development pattern: + +.. toctree:: + :maxdepth: 1 + + tutorial/enforce-unique-keys-for-sharded-collections + +.. _sharding-reference: + +Reference +--------- + +The following describes sharding commands: + +- :ref:`sharding-commands` .. STUB tutorial/replace-one-configuration-server-in-a-shard-cluster .. STUB tutorial/replace-all-configuration-servers-in-a-shard-cluster From 64b658798df4e0951bac0b58d73fa9916bbecb31 Mon Sep 17 00:00:00 2001 From: Bob Grabar Date: Mon, 10 Sep 2012 13:35:32 -0400 Subject: [PATCH 2/4] DOCS-487 updated Administration sign-post --- source/administration.txt | 39 +++++++++++++++++++++++---------------- source/replication.txt | 4 ++-- source/sharding.txt | 11 +++++------ 3 files changed, 30 insertions(+), 24 deletions(-) diff --git a/source/administration.txt b/source/administration.txt index 2d66fd1670a..392acc183e0 100644 --- a/source/administration.txt +++ b/source/administration.txt @@ -2,44 +2,52 @@ Administration ============== -Core Competencies ------------------ +This page lists the core administrative documentation, including +administration tutorials. This page also provides links to +administrative documentation for replica sets, sharding, and indexes. + +Core Documentation +------------------ + +The following is the expanded outline of the core administration +documentation: .. toctree:: - :maxdepth: 1 + :maxdepth: 2 - administration/backups - administration/import-export - administration/monitoring administration/configuration administration/ssl + administration/monitoring + administration/import-export + administration/backups -.. seealso:: For more information regarding :term:`replica set` - administration, consider: +.. seealso:: - :doc:`/administration/replica-sets` - :doc:`/administration/replication-architectures` - - For more information regarding :term:`shard cluster` - administration: consider: - - :doc:`/administration/sharding` - :doc:`/administration/sharding-architectures` + - :doc:`indexes ` + - :doc:`/administration/indexes` - For information regarding administrative concerns related to - :doc:`indexes `, see ":doc:`/administration/indexes`." - +.. index:: tutorials; administration .. _administration-tutorials: Tutorials --------- +The following tutorials describe core administrative procedures: + .. toctree:: :hidden: tutorial/recover-data-following-unexpected-shutdown tutorial/convert-replica-set-to-replicated-shard-cluster +.. TODO: Is there a way to replace this list below with the list in +.. /source/tutorial#tutorials-administration +.. That way, we'd have just one list to keep updated. -bg + - :doc:`/tutorial/expire-data` - :doc:`/tutorial/deploy-replica-set` - :doc:`/tutorial/expand-replica-set` @@ -55,4 +63,3 @@ Tutorials - :doc:`/tutorial/convert-replica-set-to-replicated-shard-cluster` - :doc:`/tutorial/add-shards-to-shard-cluster` - :doc:`/tutorial/remove-shards-from-cluster` - diff --git a/source/replication.txt b/source/replication.txt index 5bb120ba036..2109a166963 100644 --- a/source/replication.txt +++ b/source/replication.txt @@ -12,8 +12,8 @@ For an overview, see :doc:`/core/replication`. To work with members, see :doc:`administration/replica-sets`. To configure deployment architecture, see :doc:`administration/replication-architectures`. To modify read and write operations, see :doc:`applications/replication`. -For common procedures, see the :ref:`tutorials list -`. +For common procedures, see the :ref:`Tutorials +` list. Documentation ------------- diff --git a/source/sharding.txt b/source/sharding.txt index f2df8075afc..757aed9b9a6 100644 --- a/source/sharding.txt +++ b/source/sharding.txt @@ -20,10 +20,10 @@ describe sharding. For an overview, see :doc:`/core/sharding`. To configure, maintain, and troubleshoot shard clusters, see :doc:`/administration/sharding`. For deployment architectures, see -:doc:`/administration/sharding-architectures` For details on the +:doc:`/administration/sharding-architectures`. For details on the internal operations of sharding, see :doc:`/core/sharding-internals`. -For common procedures, see the :ref:`tutorials list -`. +For common procedures, see the :ref:`Tutorials ` +list. Documentation ------------- @@ -44,8 +44,7 @@ The following is the expanded outline of the main documentation: Tutorials --------- -The following tutorials describe basic administrative procedures for -deploying and managing shard clusters: +The following tutorials describe basic administrative procedures: .. toctree:: :maxdepth: 1 @@ -67,7 +66,7 @@ development pattern: Reference --------- -The following describes sharding commands: +The following reference section describes sharding commands: - :ref:`sharding-commands` From 41f736b00e2521e795d0c40f6f3fbc6121961de3 Mon Sep 17 00:00:00 2001 From: Bob Grabar Date: Mon, 10 Sep 2012 14:07:44 -0400 Subject: [PATCH 3/4] DOCS-487 updated Indexes sign-post --- source/indexes.txt | 24 +++++++++++++++--------- 1 file changed, 15 insertions(+), 9 deletions(-) diff --git a/source/indexes.txt b/source/indexes.txt index 46aca5579bd..650706da385 100644 --- a/source/indexes.txt +++ b/source/indexes.txt @@ -4,15 +4,21 @@ Indexes ======= -MongoDB's indexes make it possible to provide high performance read -operations for frequently used queries. Indexes are particularly -useful where the total size of the documents exceeds the amount of -available RAM. This section has three main documents: -:doc:`/core/indexes` that explains basic indexing concepts and -options. :doc:`/administration/indexes` that outlines procedures and -operational concerns relevant to indexing. And -:doc:`/applications/indexes` that introduces how applications may -use indexes. +Indexes provide high performance read operations for frequently used +queries. Indexes are particularly useful where the total size of the +documents exceeds the amount of available RAM. + +This page lists the main documents that describe indexes. + +For basic concepts and options, see :doc:`/core/indexes`. For procedures +and operational concerns, see :doc:`/administration/indexes`. For +information on how applications might use indexes, see +:doc:`/applications/indexes`. + +Documentation +------------- + +The following is the expanded outline of the main documentation: .. toctree:: :maxdepth: 2 From ab31320f9e729bb6c4a1d9d8522745d1528fd601 Mon Sep 17 00:00:00 2001 From: Bob Grabar Date: Mon, 10 Sep 2012 15:22:18 -0400 Subject: [PATCH 4/4] DOCS-487 edits to Sharding, Admin, Indexes --- source/administration.txt | 31 ++----------------- .../includes/tutorial-list-administration.rst | 24 ++++++++++++++ source/indexes.txt | 4 +-- source/replication.txt | 4 +-- source/sharding.txt | 17 ++-------- source/tutorial.txt | 14 +-------- 6 files changed, 34 insertions(+), 60 deletions(-) create mode 100644 source/includes/tutorial-list-administration.rst diff --git a/source/administration.txt b/source/administration.txt index 392acc183e0..26e89b258a0 100644 --- a/source/administration.txt +++ b/source/administration.txt @@ -2,15 +2,14 @@ Administration ============== -This page lists the core administrative documentation, including +This page lists the core administrative documentation and the administration tutorials. This page also provides links to administrative documentation for replica sets, sharding, and indexes. Core Documentation ------------------ -The following is the expanded outline of the core administration -documentation: +The following is the core administration documentation: .. toctree:: :maxdepth: 2 @@ -38,28 +37,4 @@ Tutorials The following tutorials describe core administrative procedures: -.. toctree:: - :hidden: - - tutorial/recover-data-following-unexpected-shutdown - tutorial/convert-replica-set-to-replicated-shard-cluster - -.. TODO: Is there a way to replace this list below with the list in -.. /source/tutorial#tutorials-administration -.. That way, we'd have just one list to keep updated. -bg - -- :doc:`/tutorial/expire-data` -- :doc:`/tutorial/deploy-replica-set` -- :doc:`/tutorial/expand-replica-set` -- :doc:`/tutorial/deploy-geographically-distributed-replica-set` -- :doc:`/tutorial/change-hostnames-in-a-replica-set` -- :doc:`/tutorial/change-oplog-size` -- :doc:`/tutorial/install-mongodb-on-linux` -- :doc:`/tutorial/install-mongodb-on-redhat-centos-or-fedora-linux` -- :doc:`/tutorial/install-mongodb-on-os-x` -- :doc:`/tutorial/install-mongodb-on-debian-or-ubuntu-linux` -- :doc:`/tutorial/recover-data-following-unexpected-shutdown` -- :doc:`/tutorial/deploy-shard-cluster` -- :doc:`/tutorial/convert-replica-set-to-replicated-shard-cluster` -- :doc:`/tutorial/add-shards-to-shard-cluster` -- :doc:`/tutorial/remove-shards-from-cluster` +.. include:: /includes/tutorial-list-administration.rst diff --git a/source/includes/tutorial-list-administration.rst b/source/includes/tutorial-list-administration.rst new file mode 100644 index 00000000000..761b2710f45 --- /dev/null +++ b/source/includes/tutorial-list-administration.rst @@ -0,0 +1,24 @@ +.. toctree:: + :maxdepth: 1 + + tutorial/install-mongodb-on-linux + tutorial/install-mongodb-on-redhat-centos-or-fedora-linux + tutorial/install-mongodb-on-os-x + tutorial/install-mongodb-on-debian-or-ubuntu-linux + tutorial/change-oplog-size + tutorial/deploy-replica-set + tutorial/deploy-geographically-distributed-replica-set + tutorial/expand-replica-set + tutorial/change-hostnames-in-a-replica-set + tutorial/recover-data-following-unexpected-shutdown + tutorial/deploy-shard-cluster + tutorial/convert-replica-set-to-replicated-shard-cluster + tutorial/add-shards-to-shard-cluster + tutorial/remove-shards-from-cluster + tutorial/expire-data + +.. toctree:: + :hidden: + + tutorial/recover-data-following-unexpected-shutdown + tutorial/convert-replica-set-to-replicated-shard-cluster diff --git a/source/indexes.txt b/source/indexes.txt index 650706da385..727dceb416f 100644 --- a/source/indexes.txt +++ b/source/indexes.txt @@ -8,8 +8,6 @@ Indexes provide high performance read operations for frequently used queries. Indexes are particularly useful where the total size of the documents exceeds the amount of available RAM. -This page lists the main documents that describe indexes. - For basic concepts and options, see :doc:`/core/indexes`. For procedures and operational concerns, see :doc:`/administration/indexes`. For information on how applications might use indexes, see @@ -18,7 +16,7 @@ information on how applications might use indexes, see Documentation ------------- -The following is the expanded outline of the main documentation: +The following is the outline of the main documentation: .. toctree:: :maxdepth: 2 diff --git a/source/replication.txt b/source/replication.txt index 2109a166963..d880738bda6 100644 --- a/source/replication.txt +++ b/source/replication.txt @@ -12,13 +12,13 @@ For an overview, see :doc:`/core/replication`. To work with members, see :doc:`administration/replica-sets`. To configure deployment architecture, see :doc:`administration/replication-architectures`. To modify read and write operations, see :doc:`applications/replication`. -For common procedures, see the :ref:`Tutorials +For procedures for performing certain replication tasks, see the :ref:`Tutorials ` list. Documentation ------------- -The following is the expanded outline of the main documentation: +The following is the outline of the main documentation: .. toctree:: :maxdepth: 2 diff --git a/source/sharding.txt b/source/sharding.txt index 757aed9b9a6..f355b9240c6 100644 --- a/source/sharding.txt +++ b/source/sharding.txt @@ -2,10 +2,6 @@ Sharding ======== -.. This was the only sign-post page with an index entry at the top, and -.. the entry seemed unlikely to be used. I've removed it. For top-level -.. pages, we have the left column. -bg - .. _sharding-background: Sharding distributes a @@ -22,13 +18,13 @@ troubleshoot shard clusters, see :doc:`/administration/sharding`. For deployment architectures, see :doc:`/administration/sharding-architectures`. For details on the internal operations of sharding, see :doc:`/core/sharding-internals`. -For common procedures, see the :ref:`Tutorials ` +For procedures for performing certain sharding tasks, see the :ref:`Tutorials ` list. Documentation ------------- -The following is the expanded outline of the main documentation: +The following is the outline of the main documentation: .. toctree:: :maxdepth: 3 @@ -44,7 +40,7 @@ The following is the expanded outline of the main documentation: Tutorials --------- -The following tutorials describe basic administrative procedures: +The following tutorials describe specific sharding procedures: .. toctree:: :maxdepth: 1 @@ -52,13 +48,6 @@ The following tutorials describe basic administrative procedures: tutorial/deploy-shard-cluster tutorial/add-shards-to-shard-cluster tutorial/remove-shards-from-cluster - -The following tutorial describes a sharding-specific application -development pattern: - -.. toctree:: - :maxdepth: 1 - tutorial/enforce-unique-keys-for-sharded-collections .. _sharding-reference: diff --git a/source/tutorial.txt b/source/tutorial.txt index 3589cce63bc..efa4765f036 100644 --- a/source/tutorial.txt +++ b/source/tutorial.txt @@ -23,19 +23,7 @@ included here, please open a :issue:`Jira Case `. Administration -------------- -.. toctree:: - :maxdepth: 1 - - tutorial/change-oplog-size - tutorial/deploy-geographically-distributed-replica-set - tutorial/deploy-replica-set - tutorial/expand-replica-set - tutorial/change-hostnames-in-a-replica-set - tutorial/recover-data-following-unexpected-shutdown - tutorial/deploy-shard-cluster - tutorial/convert-replica-set-to-replicated-shard-cluster - tutorial/add-shards-to-shard-cluster - tutorial/remove-shards-from-cluster +.. include:: /includes/tutorial-list-administration.rst .. index:: tutorials; installation .. index:: installation tutorials