From 41b8bad3c828bc240e5c9e5e578bcde55378f2c9 Mon Sep 17 00:00:00 2001 From: Chris Cho Date: Mon, 11 Nov 2019 18:16:05 -0500 Subject: [PATCH] Compact links in docs-ecosystem (#570) * add script to compact links, apply to existing docs --- source/drivers/c.txt | 4 +- source/drivers/csharp.txt | 4 +- source/drivers/cxx.txt | 2 +- source/drivers/go.txt | 4 +- source/drivers/java.txt | 2 +- source/drivers/motor.txt | 2 +- source/drivers/node.txt | 4 +- source/drivers/perl.txt | 2 +- source/drivers/php.txt | 2 +- source/drivers/pymongo.txt | 10 +-- source/drivers/scala.txt | 4 +- source/drivers/specs.txt | 4 +- source/includes/driver-table.rst | 34 +++++----- source/platforms/amazon-ec2.txt | 8 +-- source/tools/hadoop.txt | 2 +- ...ckup-and-restore-mongodb-on-amazon-ec2.txt | 18 ++--- ...ient-side-field-level-encryption-guide.txt | 6 +- tools/compact_extlinks.py | 67 +++++++++++++++++++ 18 files changed, 123 insertions(+), 56 deletions(-) create mode 100644 tools/compact_extlinks.py diff --git a/source/drivers/c.txt b/source/drivers/c.txt index d61f87748..fbb0f426a 100644 --- a/source/drivers/c.txt +++ b/source/drivers/c.txt @@ -45,7 +45,7 @@ See `Installing the MongoDB C Driver (libmongoc) and BSON library (libbson) Connect to MongoDB Atlas ------------------------ -To connect to a `MongoDB Atlas `_ cluster, use the `Atlas connection string `__ for your cluster: +To connect to a :atlas:`MongoDB Atlas ` cluster, use the :atlas:`Atlas connection string ` for your cluster: .. code-block:: c @@ -103,6 +103,6 @@ How to get help - Join our `Google Group `__. - Ask on `Stack Overflow `__. - Visit our `Support Channels `__. -- File a bug or feature request on `JIRA `__. +- File a bug or feature request on :issue:`JIRA `. diff --git a/source/drivers/csharp.txt b/source/drivers/csharp.txt index 67f5335e2..f28d84b1f 100644 --- a/source/drivers/csharp.txt +++ b/source/drivers/csharp.txt @@ -24,7 +24,7 @@ with MongoDB. - `Usage Guide `__ -- `API Reference `_ +- :api:`API Reference ` - :csharp-docs-latest:`Changelog ` @@ -43,7 +43,7 @@ For more information, see :csharp-docs-latest:`Installation Connect to MongoDB Atlas ------------------------ -To connect to a `MongoDB Atlas `_ cluster, use the `Atlas connection string `__ for your cluster: +To connect to a :atlas:`MongoDB Atlas ` cluster, use the :atlas:`Atlas connection string ` for your cluster: .. code-block:: csharp diff --git a/source/drivers/cxx.txt b/source/drivers/cxx.txt index 07bf8cb2c..4721ce092 100644 --- a/source/drivers/cxx.txt +++ b/source/drivers/cxx.txt @@ -40,7 +40,7 @@ See `Installing the mongocxx driver `_ cluster, use the `Atlas connection string `__ for your cluster: +To connect to a :atlas:`MongoDB Atlas ` cluster, use the :atlas:`Atlas connection string ` for your cluster: .. code-block:: cpp diff --git a/source/drivers/go.txt b/source/drivers/go.txt index aaac1ca78..02b1dfc3c 100644 --- a/source/drivers/go.txt +++ b/source/drivers/go.txt @@ -47,7 +47,7 @@ See `Installation `__ Connect to MongoDB Atlas ------------------------ -To connect to a `MongoDB Atlas `_ cluster, use the `Atlas connection string `__ for your cluster: +To connect to a :atlas:`MongoDB Atlas ` cluster, use the :atlas:`Atlas connection string ` for your cluster: .. code-block:: go @@ -82,7 +82,7 @@ How to get help - Join our `Google Group `__. - Ask on `Stack Overflow `__. - Visit our `Support Channels `__. -- See the `project JIRA `__ to raise issues or request features. +- See the :issue:`project JIRA ` to raise issues or request features. diff --git a/source/drivers/java.txt b/source/drivers/java.txt index 25db37885..e7f582280 100644 --- a/source/drivers/java.txt +++ b/source/drivers/java.txt @@ -54,7 +54,7 @@ management system. See Connect to MongoDB Atlas ------------------------ -To connect to a `MongoDB Atlas `_ cluster, use the `Atlas connection string `__ for your cluster: +To connect to a :atlas:`MongoDB Atlas ` cluster, use the :atlas:`Atlas connection string ` for your cluster: .. code-block:: java diff --git a/source/drivers/motor.txt b/source/drivers/motor.txt index e3526872e..2a1c630e4 100644 --- a/source/drivers/motor.txt +++ b/source/drivers/motor.txt @@ -50,7 +50,7 @@ Motor on all platforms: Connect to MongoDB Atlas ------------------------ -To connect to a `MongoDB Atlas `_ cluster, use the `Atlas connection string `__ for your cluster: +To connect to a :atlas:`MongoDB Atlas ` cluster, use the :atlas:`Atlas connection string ` for your cluster: .. code-block:: python diff --git a/source/drivers/node.txt b/source/drivers/node.txt index a946c12f3..cee2196b9 100644 --- a/source/drivers/node.txt +++ b/source/drivers/node.txt @@ -63,8 +63,8 @@ This will download the MongoDB driver and add a dependency entry in your package Connect to MongoDB Atlas ------------------------ -To connect to a `MongoDB Atlas `_ cluster, use the -`Atlas connection string `__ for your cluster: +To connect to a :atlas:`MongoDB Atlas ` cluster, use the +:atlas:`Atlas connection string ` for your cluster: .. code-block:: javascript diff --git a/source/drivers/perl.txt b/source/drivers/perl.txt index 5501e207b..397ea5a8c 100644 --- a/source/drivers/perl.txt +++ b/source/drivers/perl.txt @@ -62,7 +62,7 @@ for more information. Connect to MongoDB Atlas ------------------------ -To connect to a `MongoDB Atlas `_ cluster, use the `Atlas connection string `__ for your cluster: +To connect to a :atlas:`MongoDB Atlas ` cluster, use the :atlas:`Atlas connection string ` for your cluster: .. code-block:: perl diff --git a/source/drivers/php.txt b/source/drivers/php.txt index f88ae843a..a4418c830 100644 --- a/source/drivers/php.txt +++ b/source/drivers/php.txt @@ -78,7 +78,7 @@ Additional installation instructions may be found in the Connect to MongoDB Atlas ------------------------ -To connect to a `MongoDB Atlas `_ cluster, use the `Atlas connection string `__ for your cluster: +To connect to a :atlas:`MongoDB Atlas ` cluster, use the :atlas:`Atlas connection string ` for your cluster: .. code-block:: php diff --git a/source/drivers/pymongo.txt b/source/drivers/pymongo.txt index ac4622a9f..4a3196c33 100644 --- a/source/drivers/pymongo.txt +++ b/source/drivers/pymongo.txt @@ -17,11 +17,11 @@ Introduction **PyMongo** is the recommended way to work with MongoDB from Python. -- `Tutorial `__ +- :api:`Tutorial ` -- `API Reference `_ +- :api:`API Reference ` -- `Changelog `__ +- :api:`Changelog ` - `Source Code `__ @@ -62,14 +62,14 @@ To upgrade using pip: $ python -m pip install --upgrade pymongo -See `Installation `__ for more +See :api:`Installation ` for more ways to install. Connect to MongoDB Atlas ------------------------ -To connect to a `MongoDB Atlas `_ cluster, use the `Atlas connection string `__ for your cluster: +To connect to a :atlas:`MongoDB Atlas ` cluster, use the :atlas:`Atlas connection string ` for your cluster: .. code-block:: python diff --git a/source/drivers/scala.txt b/source/drivers/scala.txt index 33015df01..f31e8680e 100644 --- a/source/drivers/scala.txt +++ b/source/drivers/scala.txt @@ -41,7 +41,7 @@ The recommended way to get started using the driver in your project is with a de Connect to MongoDB Atlas ------------------------ -To connect to a `MongoDB Atlas `_ cluster, use the `Atlas connection string `__ for your cluster: +To connect to a :atlas:`MongoDB Atlas ` cluster, use the :atlas:`Atlas connection string ` for your cluster: .. code-block:: scala @@ -85,7 +85,7 @@ How to get help - Join our `Google Group `__. - Ask on `Stack Overflow `__. - Visit our `Support Channels `__. -- See our `JIRA `__ to raise issues or request features. +- See our :issue:`JIRA ` to raise issues or request features. diff --git a/source/drivers/specs.txt b/source/drivers/specs.txt index 6442d96ba..e794d118a 100644 --- a/source/drivers/specs.txt +++ b/source/drivers/specs.txt @@ -63,7 +63,7 @@ what they apply to. - |checkmark| - - - * - `TCP Keepalive `_ + * - :issue:`TCP Keepalive ` - |checkmark| - - @@ -151,7 +151,7 @@ what they apply to. - |checkmark| - - - * - `OP_INSERT, OP_UPDATE, OP_REMOVE, getLastError `_ + * - :manual:`OP_INSERT, OP_UPDATE, OP_REMOVE, getLastError ` - |checkmark| - - diff --git a/source/includes/driver-table.rst b/source/includes/driver-table.rst index fe82f800f..ee0725aae 100644 --- a/source/includes/driver-table.rst +++ b/source/includes/driver-table.rst @@ -13,93 +13,93 @@ - `Releases `__ - `Source `__ - `API `__ - - `JIRA `__ + - :issue:`JIRA ` - * - :doc:`C++ ` - `Releases `__ - `Source `__ - `API `__ - - `JIRA `__ + - :issue:`JIRA ` - * - :doc:`C# ` - `Releases `__ - `Source `__ - `API `__ - - `JIRA `__ + - :issue:`JIRA ` - * - :doc:`Go ` - `Releases `__ - `Source `__ - `API `__ - - `JIRA `__ + - :issue:`JIRA ` - * - :doc:`Java ` - `Releases `__ - `Source `__ - `API `__ - - `JIRA `__ + - :issue:`JIRA ` - `Course `__ * - :doc:`Node.js ` - `Releases `__ - `Source `__ - `API `__ - - `JIRA `__ + - :issue:`JIRA ` - `Course `__ * - :doc:`Perl ` - `Releases `__ - `Source `__ - `API `__ - - `JIRA `__ + - :issue:`JIRA ` - * - :doc:`PHP ` - `Releases `__ - `Source `__ - `API `__ - - `JIRA `__ + - :issue:`JIRA ` - * - :doc:`Python ` - `Releases `__ - `Source `__ - - `API `__ - - `JIRA `__ + - :api:`API ` + - :issue:`JIRA ` - `Course `__ * - :ref:`Motor (Python async)` - `Releases `__ - `Source `__ - `API `__ - - `JIRA `__ + - :issue:`JIRA ` - * - `Ruby `_ - `Releases `__ - `Source `__ - - `API `__ - - `JIRA `__ + - :api:`API ` + - :issue:`JIRA ` - * - `Mongoid (Ruby ODM) `_ - `Releases `__ - `Source `__ - `API `__ - - `JIRA `__ + - :issue:`JIRA ` - * - :doc:`Scala ` - `Releases `__ - `Source `__ - `API `__ - - `JIRA `__ + - :issue:`JIRA ` - .. * - :doc:`Haskell ` - `Releases `__ - - `API `__ - - `JIRA `__ + - :api:`API ` + - :issue:`JIRA ` diff --git a/source/platforms/amazon-ec2.txt b/source/platforms/amazon-ec2.txt index 941300698..fa9d82f0e 100644 --- a/source/platforms/amazon-ec2.txt +++ b/source/platforms/amazon-ec2.txt @@ -159,11 +159,11 @@ Change the default TCP keepalive time to 300 seconds. See our Enhanced Networking on Supported Instance Types ``````````````````````````````````````````````` -When available, enable AWS's `Enhanced Networking -`_ +When available, enable AWS's :aws-docs:`Enhanced Networking +` for your instance. Not all instance types support Enhanced Networking. -Refer to the `AWS documentation -`_ +Refer to the :aws-docs:`AWS documentation +` for more information. Secure Instances diff --git a/source/tools/hadoop.txt b/source/tools/hadoop.txt index 5d163df6f..56a424a8b 100644 --- a/source/tools/hadoop.txt +++ b/source/tools/hadoop.txt @@ -28,7 +28,7 @@ comprehensive `wiki If you have questions please email the `mongodb-user Mailing List `_. For any issues please -file a ticket in `Jira `_. +file a ticket in :issue:`Jira `. This guide also includes the following documentation: diff --git a/source/tutorial/backup-and-restore-mongodb-on-amazon-ec2.txt b/source/tutorial/backup-and-restore-mongodb-on-amazon-ec2.txt index 7bcb78585..997b98410 100644 --- a/source/tutorial/backup-and-restore-mongodb-on-amazon-ec2.txt +++ b/source/tutorial/backup-and-restore-mongodb-on-amazon-ec2.txt @@ -104,7 +104,7 @@ Backup the Database Files ------------------------- There are several ways to create an EBS Snapshot. The following examples use the -`AWS command line `_ +:aws-docs:`AWS command line ` tool. Find the EBS Volumes Associated with MongoDB @@ -219,9 +219,9 @@ Create the EBS Snapshot ~~~~~~~~~~~~~~~~~~~~~~~ Create the snapshot for each device. Using the -`ec2-create-snapshot `_ +:aws-docs:`ec2-create-snapshot ` command, use the Volume Id for the device listed by the -`ec2-describe-instances `_ +:aws-docs:`ec2-describe-instances ` command. .. code-block:: sh @@ -270,11 +270,11 @@ I/O load of the verification processing. Describe the Snapshots ~~~~~~~~~~~~~~~~~~~~~~ -Using the `ec2-describe-snapshots `_ +Using the :aws-docs:`ec2-describe-snapshots ` command, find the snapshots that make up the backup. Using a filter on the ``description`` field, snapshots associated with the given backup are easily found. The search text used should match the text used in the ``-d`` -flag passed to `ec2-create-snapshot `_ command when the backup was made. +flag passed to :aws-docs:`ec2-create-snapshot ` command when the backup was made. .. code-block:: sh @@ -287,7 +287,7 @@ flag passed to `ec2-create-snapshot `_ +Using the :aws-docs:`ec2-create-volume ` command, create a new volumes based on each of the snapshots that make up the backup. @@ -305,7 +305,7 @@ up the backup. Attach the New Volumes to the Instance ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Using the `ec2-attach-volume `_ +Using the :aws-docs:`ec2-attach-volume ` command, attach each volume to the instance where the backup will be verified. @@ -397,9 +397,9 @@ Restore uses the same basic steps as the verification process: 1. :manual:`db.shutdownServer() ` -2. `ec2-create-volume `_ +2. :aws-docs:`ec2-create-volume ` and - `ec2-attach-volume `_. + :aws-docs:`ec2-attach-volume `. 3. Mount the file system. diff --git a/source/use-cases/client-side-field-level-encryption-guide.txt b/source/use-cases/client-side-field-level-encryption-guide.txt index 106943dc0..38f98c333 100644 --- a/source/use-cases/client-side-field-level-encryption-guide.txt +++ b/source/use-cases/client-side-field-level-encryption-guide.txt @@ -227,8 +227,8 @@ uses an encryption strategy called *envelope encryption* in which keys used to encrypt/decrypt data (called **data encryption keys**) are encrypted with another key (called the **master key**). For more information on the features of envelope encryption and key management -concepts, see `AWS Key Management Service Concepts -`_. +concepts, see :aws-docs:`AWS Key Management Service Concepts +`. The master key, used by the MongoDB driver to create and encrypt data keys, should be stored remotely in a :wikipedia:`Key Management System @@ -839,7 +839,7 @@ check out the reference docs in the server manual: .. tab:: :tabid: java-sync - For additional information on CSFLE, see the `official Java driver documentation `_ + For additional information on CSFLE, see the :java-docs-latest:`official Java driver documentation ` .. tab:: :tabid: nodejs diff --git a/tools/compact_extlinks.py b/tools/compact_extlinks.py new file mode 100644 index 000000000..627f6f66a --- /dev/null +++ b/tools/compact_extlinks.py @@ -0,0 +1,67 @@ +# This script takes existing extlinks and applies them to existing docs. +# The original files are saved with the .orig suffix. +# Usage: +# python compact_extlinks.py +# E.g.: python compact_extlinks.py ../source + +import os +import sys +import re +from collections import defaultdict +from shutil import copyfile + +sys.path.append("..") +from conf import extlinks + +doc_root = sys.argv[1] + +url_valid_chars = r"[\-\._~\:/?#\[\]@!\$&\'\(\)\*\+\,;%=\w]+" +link_valid_chars = r"[\s\w!\"#$%&\'\(\)\*\+,\.\/:;=\?@\[\]\^\_\{\|\}\~\-]" + +# return: dict of extlink tag (e.g. aws-docs) => regular expression for matching rst +def extlinks_regexp(links=extlinks): + re_dict = dict() + + regexps = [] + for k, v in links.items(): + url = re.sub(r'https?://(\S+)\%s$', '\g<1>', v[0]) + + re_dict[k] = re.compile(r"(`)(" + link_valid_chars + r"*)<(\s*https?://" + url + r")(" + url_valid_chars + r")(\s*>\s*`_+)", re.MULTILINE) + + return re_dict + +link_regex = extlinks_regexp() + +urls = defaultdict(int) +num_scanned = 0 +num_created = 0 + +for dirpath, dirnames, filenames in os.walk(doc_root): + for filename in [f for f in filenames if (f.endswith(".txt") or f.endswith(".rst"))]: + updated = False + + filepath = "/".join([dirpath, filename]) + with open(filepath, 'r') as file: + num_scanned += 1 + data = file.read() + + for k, regexpr in link_regex.items(): + result = re.subn(regexpr, (":" + k + ":`\g<2><\g<4>>`"), data) + + if result[1] > 0: #num updates + updated = True + data = result[0] + + if updated: + num_created += 1 + # save the original + copyfile(filepath, (filepath + ".orig")) + + fh = open(filepath, 'w') + fh.write(data) + fh.close() + else: + continue + +print("Files scanned: %i" % num_scanned) +print("New files created: %i" % num_created)