Skip to content

Commit 6b0a23b

Browse files
jason-price-mongodbjason-price-mongodb
authored
Merge pull request #166 from davemungo/DOCSP-16500-add-snippets-feature
DOCSP-16500-add-snippets-feature
2 parents 31750db + 0ddc312 commit 6b0a23b

26 files changed

+1623
-10
lines changed

‎.DS_Store

-6 KB
Binary file not shown.

‎.gitignore

Lines changed: 90 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,90 @@
1+
build/*
2+
*.swp
3+
.#*
4+
\#*#
5+
*__pycache__*
6+
*.pyc
7+
*.pyo
8+
*.bak
9+
.DS_Store
10+
source/includes/hash.rst
11+
source/includes/install-*-release-*.rst
12+
13+
source/includes/toc-*.rst
14+
source/includes/dfn*.rst
15+
source/includes/manpage-options-auth-mongo.rst
16+
source/includes/manpage-options-ssl-settings.rst
17+
source/includes/manpage-options-audit-settings.rst
18+
TAGS
19+
mongodb-domain.yaml
20+
composite-pages.yaml
21+
!bin/*/mongodb-domain.yaml
22+
meta.yaml
23+
build
24+
source/driver-examples/
25+
*~
26+
source/reference/*/*.rst
27+
source/reference/*/*/*.rst
28+
source/reference/*.rst
29+
source/compass/images/*
30+
source/images/compass/
31+
giza.log
32+
pdfs.yaml
33+
intersphinx.yaml
34+
!bin/*/pdfs.yaml
35+
source/includes/hash.rst
36+
docs_meta.yaml
37+
!bin/docs_meta.yaml
38+
fabfile
39+
source/includes/toc/
40+
source/includes/table/
41+
source/includes/steps/
42+
source/includes/generated/includes-overview.rst
43+
source/includes/generated/
44+
source/includes/option/
45+
source/includes/changelogs/*.rst
46+
!source/includes/changelogs/releases/*.rst
47+
primer/source/includes/toc/
48+
primer/source/includes/table/
49+
primer/source/includes/steps/
50+
primer/source/includes/generated/includes-overview.rst
51+
primer/source/includes/generated/
52+
primer/source/includes/option/
53+
primer/source/includes/hash.rst
54+
primer/source/.static
55+
primer/source/*.rst
56+
primer/source/core/*.rst
57+
primer/source/includes/example*.txt
58+
primer/source/includes/example-*.rst
59+
primer/source/includes/driver-table.rst
60+
primer/source/includes/fact-installation-bind-ip-default-in-config.rst
61+
primer/source/includes/fact-installation-directories.rst
62+
primer/source/includes/fact-selinux-redhat-options.rst
63+
primer/source/includes/list-mongodb-org-packages.rst
64+
primer/source/includes/note-package-change.rst
65+
primer/source/includes/note-suse-ulimit.rst
66+
primer/source/tutorial/*.rst
67+
primer/source/includes/toc-*yaml
68+
primer/source/includes/steps-*yaml
69+
!primer/source/includes/steps-client-*.yaml
70+
!primer/source/includes/steps-getting-started-prereq.yaml
71+
primer/source/includes/release-*yaml
72+
primer/source/tutorial/install-mongodb-on-*.txt
73+
!primer/config/intersphinx.yaml
74+
!primer/config/published_branches.yaml
75+
!primer/source/includes/toc-primer-*yaml
76+
!primer/source/includes/steps-primer*yaml
77+
!primer/source/includes/client-*rst
78+
!primer/source/includes/prereq-*.rst
79+
primer/source/images/*.png
80+
primer/source/images/*.rst
81+
primer/source/images/*.svg
82+
primer/source/includes/*.cpp
83+
primer/source/includes/*.java
84+
primer/source/includes/*.cs
85+
*.mo
86+
.stub
87+
primer/source/includes/table-linux-kernel-version-production.yaml
88+
venv
89+
.vscode
90+
changelogs/.mongodb-jira.yaml

‎snooty.toml

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,12 @@ title = "MongoDB Shell"
33

44
intersphinx = ["https://docs.mongodb.com/manual/objects.inv"]
55

6-
toc_landing_pages = ["/run-commands", "/crud", "/field-level-encryption", "/write-scripts"]
6+
toc_landing_pages = ["/run-commands",
7+
"/crud",
8+
"/field-level-encryption",
9+
"/write-scripts",
10+
"/snippets"
11+
]
712

813
[constants]
914

‎source/changelog.txt

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -249,6 +249,9 @@ New features in this release:
249249
`Versioned API
250250
<https://docs.mongodb.com/v5.0/reference/versioned-api/>`__.
251251

252+
- :ref:`Snippets <snip-overview>`. An experimental feature that
253+
allows users to create custom shell extensions.
254+
252255
Bug fixes in this release:
253256

254257
- ``mongosh`` can now connect to a replica set containing unhealthy nodes.

‎source/includes/fact-snippet-registries.rst

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
The snippets feature uses the
2+
`npm package manager <https://www.npmjs.com/package/npm>`__ to install
3+
snippets from a pre-specified registry. You can configure your local
4+
:binary:`~bin.mongosh` to use one or more registries:
5+
6+
- The `community registry
7+
<https://github.com/mongodb-labs/mongosh-snippets/tree/main/snippets>`__
8+
that is maintained by MongoDB
9+
- A private registry that you maintain
10+
- Multiple registries used together
11+

‎source/includes/steps-define-a-new-registry.yaml

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
1+
title: Create A GitHub Repository.
2+
stepnum: 1
3+
level: 4
4+
ref: snip-step-create-github-repository
5+
content: |
6+
7+
You will push snippet packages from your GitHub repository to your
8+
npm registry.
9+
10+
Follow the `GitHub documentation
11+
<https://docs.github.com/en/pages/getting-started-with-github-pages/creating-a-github-pages-site>`__
12+
to create a repository.
13+
14+
15+
---
16+
title: Create An npm Registry.
17+
stepnum: 2
18+
level: 4
19+
ref: snip-step-create-npm-registry
20+
content: |
21+
22+
Follow the `npm registry documentation
23+
<https://docs.npmjs.com/cli/v7/using-npm/registry>`__ to create a
24+
registry.
25+
26+
---
27+
28+
title: Update ``snippetIndexSourceURLs``.
29+
stepnum: 3
30+
level: 4
31+
ref: snip-step-update-snippetIndexSourceURL
32+
content: |
33+
34+
To make the new registry available to your local
35+
:binary:`~bin.mongosh` installation, update the
36+
``snippetIndexSourceURLs`` configuration settings.
37+
38+
.. code-block::
39+
40+
config.set('snippetIndexSourceURLs',
41+
'https://github.com/YOUR_COMPANY/PATH_TO_YOUR_REPOSITORY/index.bson.br;'
42+
+ config.get('snippetIndexSourceURLs') )
43+
---
44+
45+
title: Update ``snippetRegistryURL``.
46+
stepnum: 4
47+
level: 4
48+
ref: snip-step-update-snippetRegistryURL
49+
content: |
50+
51+
If you created a registry that is hosted outside npm, update
52+
``snippetRegistryURL`` to point to the new registry.
53+

‎source/includes/steps-snip-contribute.yaml

Lines changed: 67 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
1+
title: Complete the Contributor Agreement.
2+
stepnum: 1
3+
level: 4
4+
ref: snip-step-submit-read-agreement
5+
content: |
6+
7+
Read and complete the
8+
`MongoDB Contributor Agreement <https://www.mongodb.com/legal/contributor-agreement>`__.
9+
---
10+
11+
title: Clone the Repository.
12+
stepnum: 2
13+
level: 4
14+
ref: snip-step-submit-clone-repo
15+
content: |
16+
17+
Fork and clone the
18+
`snippet project repository <https://github.com/mongodb-labs/mongosh-snippets>`__
19+
from GitHub.
20+
---
21+
22+
title: Create Your Package Directory.
23+
stepnum: 3
24+
level: 4
25+
ref: snip-step-submit-create-package-directory
26+
content: |
27+
28+
Add a new directory for your code under
29+
`snippets/ <https://github.com/mongodb-labs/mongosh-snippets/tree/main/snippets>`__.
30+
Give it a descriptive name.
31+
---
32+
33+
title: Create Your Package.
34+
stepnum: 4
35+
level: 4
36+
ref: snip-step-submit-create-package
37+
content: |
38+
39+
Create your snippet package. Be sure it contains the following files:
40+
41+
- ``package.json``
42+
- ``index.js``
43+
- ``README.md``
44+
- ``LICENSE``
45+
46+
You do not have to create a registry index file. If your snippet
47+
package is accepted, MongoDB will update the registry index file.
48+
---
49+
50+
title: Commit your changes.
51+
stepnum: 5
52+
level: 4
53+
ref: snip-step-submit-commit-your-code
54+
content: |
55+
56+
Commit your changes to your GitHub repository.
57+
---
58+
59+
title: Submit Your Snippet Code.
60+
stepnum: 6
61+
level: 4
62+
ref: snip-step-submit-your-code
63+
content: |
64+
65+
Open a pull request against the `snippet project repository
66+
<https://github.com/mongodb-labs/mongosh-snippets>`__.
67+

‎source/includes/steps-snip-install.yaml

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
title: Refresh Metadata.
2+
stepnum: 1
3+
level: 4
4+
ref: snip-step-refresh-metadata
5+
content: |
6+
7+
Refresh the snippet metadata in your local :binary:`~bin.mongosh`.
8+
9+
.. code-block:: shell
10+
11+
snippet refresh
12+
---
13+
14+
title: Install the Snippet.
15+
stepnum: 2
16+
level: 4
17+
ref: snip-step-install-the-snippet
18+
content: |
19+
20+
Install the snippet.
21+
22+
.. code-block:: shell
23+
24+
snippet install YOUR_NEW_SNIPPET

‎source/includes/steps-snip-package-files.yaml

Lines changed: 118 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,118 @@
1+
title: Fork the Community Repository.
2+
stepnum: 1
3+
level: 4
4+
ref: snip-step-fork-the-repo
5+
content: |
6+
7+
If you plan to contribute to the community repository, fork the
8+
snippets `project repository
9+
<https://github.com/mongodb-labs/mongosh-snippets>`__.
10+
11+
You do not have to fork the community repository if you want to
12+
create a private repo, but you should manually recreate a
13+
similar directory structure as you work through the following
14+
steps.
15+
---
16+
17+
title: Create a Package Directory.
18+
stepnum: 2
19+
level: 4
20+
ref: snip-step-create-directory
21+
content: |
22+
23+
Create a directory for your snippet package under the ``snippets``
24+
directory in the forked repository. This directory will
25+
contain the code for your script and several metadata files.
26+
27+
This example shows directories for two snippet packages,
28+
``decrypt-cards`` and ``update-auth``. The contents of the
29+
`community snippets
30+
<https://github.com/mongodb-labs/mongosh-snippets/tree/main/snippets>`__
31+
directories are omitted for clarity.
32+
33+
.. code-block:: shell
34+
:copyable: false
35+
:emphasize-lines: 8-13, 18-22
36+
37+
mongo-snippets
38+
|
39+
├── scripts
40+
│   ├── make-index.js
41+
│   └── show-index.js
42+
└── snippets
43+
├── analyze-schema
44+
├── decrypt-cards
45+
│   ├── LICENSE-Community.txt
46+
│   ├── README.md
47+
│   ├── error-matchers.js
48+
│   ├── index.js
49+
│   └── package.json
50+
├── mock-collection
51+
├── mongocompat
52+
├── resumetoken
53+
├── spawn-mongod
54+
└── update-auth
55+
├── LICENSE
56+
├── README.md
57+
├── index.js
58+
└── package.json
59+
---
60+
61+
title: Create ``README.md``.
62+
stepnum: 3
63+
level: 4
64+
ref: snip-step-readme
65+
content: |
66+
67+
Create a ``README.md``. The ``README.md`` describes how to use your
68+
code. This file is displayed when a user enters ``snippet help`` for
69+
your snippet.
70+
---
71+
72+
title: Create ``LICENSE``.
73+
stepnum: 4
74+
level: 4
75+
ref: snip-step-license
76+
content: |
77+
78+
Create a ``LICENSE`` file. You will need to enter a license
79+
identifier string later, so try to chose a license from the
80+
`SPDX license list <https://www.npmjs.com/package/spdx>`__.
81+
---
82+
83+
title: Create ``index.js``.
84+
stepnum: 5
85+
level: 4
86+
ref: snip-step-index.js
87+
content: |
88+
89+
Create an ``index.js`` file.
90+
91+
- This file contains the entry point to your code that is exposed in
92+
the :binary:`~bin.mongosh` console.
93+
- The script is written in JavaScript and defines your new functions.
94+
- The script can be in a single file or multiple files.
95+
- The script can call other files and local or remote npm modules.
96+
To ``require()`` a remote npm module use the construction:
97+
98+
.. code-block:: javascript
99+
100+
const localRequire = require('module').createRequire(__filename);)
101+
102+
For an example, see
103+
`index.js <https://github.com/mongodb-labs/mongosh-snippets/blob/main/snippets/resumetoken/index.js>`__
104+
in the ``resumetoken`` snippet.
105+
- ``index.js`` is referenced in :ref:`package.json <snip-prep-package.json>`.
106+
- The MongoDB repository has `example code
107+
<https://github.com/mongodb-labs/mongosh-snippets>`__.
108+
109+
.. tip::
110+
111+
If you have an existing script, either rename it ``index.js`` or
112+
create an ``index.js`` file to load it. For an example of an
113+
``index.js`` file that loads other scripts, see `this one
114+
<https://github.com/mongodb-labs/mongosh-snippets/blob/main/snippets/mongocompat/index.js>`__
115+
in the `community repository
116+
<https://github.com/mongodb-labs/mongosh-snippets>`__.
117+
118+

0 commit comments

Comments
 (0)