(DOCSP-26570): Fixed build errors. (#130)

* (DOCSP-26570): Fixed build errors.

* (DOCSP-26570): Incorporated Chris's feedback.

Author: corryroot

snooty.toml

@@ -17,6 +17,8 @@ markdown = "Markdown"
 docutils = "Docutils"
 sphinx = "Sphinx"
 docs-platform = "Docs Platform Team"
+db-example = "+db+"
 
 [substitutions]
 mdbsg = "MongoDB Style Guide"
+service = "Atlas"

source/images-guide.txt

@@ -17,9 +17,9 @@ Whenever possible, you should publish diagrams in SVG form. This
 provides a crisp image at any screen resolution with a small file
 size.
 
-First install `mut <https://github.com/mongodb/mut>`_,
-`Inkscape <http://inkscape.org/>`_, and
-`svgo <https://github.com/svg/svgo>`_.
+First install `mut <https://github.com/mongodb/mut>`__,
+`Inkscape <http://inkscape.org/>`__, and
+`svgo <https://github.com/svg/svgo>`__.
 
 Place your SVG in ``source/images/``. If you named your SVG
 ``foo.svg``, then run the following from within that directory:
@@ -61,13 +61,13 @@ itself should not be wider than 1000px.
    content.
 
    It may make sense to use
-   `mozjpeg <https://github.com/mozilla/mozjpeg>`_ if you need lossy
-   compression; `imagemagick <http://imagemagick.org/>`_ to resize images;
-   and a `Ninja <http://ninja-build.org/>`_ file to put the pieces
+   `mozjpeg <https://github.com/mozilla/mozjpeg>`__ if you need lossy
+   compression; `imagemagick <http://imagemagick.org/>`__ to resize images;
+   and a `Ninja <http://ninja-build.org/>`__ file to put the pieces
    together.
 
 The default ``libpng`` encoder does not create optimal PNG files, so
-install `zopflipng <https://github.com/google/zopfli>`_. To compress a
+install `zopflipng <https://github.com/google/zopfli>`__. To compress a
 PNG, use the following template:
 
 .. code-block:: sh

source/includes/steps-configure-git.yaml

@@ -1,7 +1,7 @@
 title: "Fork these repositories into your own GitHub account."
 ref: fork-repos
 content: |
-  `This guide from GitHub <https://guides.github.com/activities/forking/>`_ covers the specifics.
+  `This guide from GitHub <https://guides.github.com/activities/forking/>`__ covers the specifics.
 
   - https://github.com/mongodb/docs
   - https://github.com/mongodb/docs-ecosystem

source/includes/steps-create-ssh-key.yaml

@@ -42,5 +42,5 @@ title: "Add this certificate to your GitHub account."
 ref: add-cert-to-github
 content: |
   For specific instructions, see 
-  `GitHub <https://help.github.com/articles/adding-a-new-ssh-key-to-your-github-account/>`_.
+  `GitHub <https://help.github.com/articles/adding-a-new-ssh-key-to-your-github-account/>`__.
 ...

source/includes/steps-get-aws-keys.yaml

@@ -1,15 +1,15 @@
 title: "Login to your AWS Account."
 ref: login-aws
 content: |
-  Login to `AWS for the Education department <https://idp.mongodb.com/simplesaml/saml2/idp/SSOService.php?spentityid=urn:amazon:webservices:univ-training-991734710418>`_.
+  Login to `AWS for the Education department <https://idp.mongodb.com/simplesaml/saml2/idp/SSOService.php?spentityid=urn:amazon:webservices:univ-training-991734710418>`__.
 
 ---
 title: "Connect to your AWS Instance."
 ref: connect-aws-instance
 content: |
 
   a. After you have `created an instance 
-     <https://gist.github.com/atsansone/52e63e3f22811adcc8b6#create-an-aws-instance>`_, 
+     <https://gist.github.com/atsansone/52e63e3f22811adcc8b6#create-an-aws-instance>`__, 
      click on radio button for your instance.
 
   b. Click :guilabel:`Connect`.

source/includes/steps-install-aws-keys.yaml

@@ -7,14 +7,14 @@ content: |
   
   a. Create a new Group.
   
-  b. Click `Settings`.
+  b. Click :guilabel:`Settings`.
   
-  c. Click `Billing/Subscriptions`.
+  c. Click :guilabel:`Billing/Subscriptions`.
   
   d. Click :guilabel:`Pencil Icon` to the right of :guilabel:`Payment Method`
      to activate your account.
   
-  e. Use `Stripe's Test Cards <https://stripe.com/docs/testing>`_ to 
+  e. Use `Stripe's Test Cards <https://stripe.com/docs/testing>`__ to 
      complete your payment setup.
 
 ---
@@ -38,7 +38,7 @@ content: |
           - Action
  
         * - Authentication Method
-          - Choose `Access Key/Secret`.
+          - Choose :guilabel:`Access Key/Secret`.
  
         * - Access Key ID
           - Enter the Access Key that |automationperson| gave you.

source/includes/steps-install-ssh-key.yaml

@@ -4,9 +4,9 @@ ref: login-cloud-manager-2
 title: "Add the SSH Public Key."
 ref: add-ssh-key
 content: |
-  a. Click `Settings`.
+  a. Click :guilabel:`Settings`.
 
-  b. Click `Provisioning Settings`.
+  b. Click :guilabel:`Provisioning Settings`.
 
   c. Click :guilabel:`Add SSH Public Key`.
 

source/includes/steps-repo.yaml

@@ -118,7 +118,7 @@ title: Fork the repo
 ref: fork-repo
 content: |
 
-  Go ahead and fork the repo on github if you wish to follow the docs model of github usage. `Fork a repo <https://help.github.com/en/articles/fork-a-repo>`_.
+  Go ahead and fork the repo on github if you wish to follow the docs model of github usage. `Fork a repo <https://help.github.com/en/articles/fork-a-repo>`__.
 
   This is not a requirement if your team follows a different workflow. If you wish to branch off the root repository, skip this step entirely.
 

source/includes/styles/corrections.rst

@@ -12,7 +12,7 @@ integrate it into the existing resource.
 
 If you have questions, don't hesitate to open a ticket in the
 `Documentation Jira Project <https://jira.mongodb.org/browse/DOCS>`_
-or contact the `documentation team <mailto:[email protected]>`_.
+or contact the `documentation team <mailto:[email protected]>`__.
 
 Global Organization
 -------------------
@@ -56,25 +56,24 @@ Tools
 -----
 
 The organization of the site, like all Sphinx sites derives from the
-:rst:dir:`toctree <sphinx:toctree>` structure. However, in order to annotate
+``toctree`` structure. However, in order to annotate
 the table of contents and provide additional flexibility, the MongoDB
-documentation generates :rst:dir:`toctree` structures using
+documentation generates ``toctree`` structures using
 data from YAML files stored in the ``source/includes/``
 directory. These files start with ``ref-toc`` or ``toc`` and generate
 output in the ``source/includes/toc/`` directory. Briefly this system
 has the following behavior:
 
 - files that start with ``ref-toc`` refer to the documentation of API
   objects (i.e. commands, operators and methods), and the build
-  system generates files that hold :rst:dir:`toctree <sphinx:toctree>`
+  system generates files that hold ``toctree``
   directives as well as files that hold *tables* that list objects and
   a brief description.
 
 - files that start with ``toc`` refer to all other documentation and
-  the build system generates files that hold :rst:dir:`toctree
-  <sphinx:toctree>`  directives as well as files that hold
-  *definition lists* that contain links to the documents and short
-  descriptions the content.
+  the build system generates files that hold ``toctree``  directives as 
+  well as files that hold *definition lists* that contain links to the 
+  documents and short descriptions the content.
 
 - file names that have ``spec`` following ``toc`` or ``ref-toc`` will
   generate aggregated tables or definition lists and allow ad-hoc

source/organization.txt

@@ -9,7 +9,7 @@ Commits
 
 When relevant, include a Jira case identifier in a commit
 message. Reference documentation cases when applicable, but feel free to
-reference other cases from `jira.mongodb.org <http://jira.mongodb.org/>`_.
+reference other cases from `jira.mongodb.org <http://jira.mongodb.org/>`__.
 
 Remove trailing whitespaces in the source file.
 
@@ -33,20 +33,20 @@ Collaboration
 To propose a change to the documentation, do either of the following:
 
 - Open a ticket in the `documentation project
-  <https://jira.mongodb.org/browse/DOCS>`_ proposing the change.
+  <https://jira.mongodb.org/browse/DOCS>`__ proposing the change.
   Someone on the documentation team will make the change and be in
   contact with you so that you can review the change.
 
-- Using `GitHub <https://github.com/>`_, fork the `mongodb/docs
-  repository <https://github.com/mongodb/docs>`_, commit your changes,
+- Using `GitHub <https://github.com/>`__, fork the `mongodb/docs
+  repository <https://github.com/mongodb/docs>`__, commit your changes,
   and issue a pull request. Someone on the documentation team will
   review and incorporate your change into the documentation.
 
 Builds
 ------
 
 Building the documentation is useful because `Sphinx
-<http://sphinx.pocoo.org/>`_ and docutils can catch numerous errors in
+<http://sphinx.pocoo.org/>`__ and docutils can catch numerous errors in
 the format and syntax of the documentation. Additionally, having
 access to an example documentation as it *will* appear to the users is
 useful for providing more effective basis for the review
@@ -208,7 +208,7 @@ methods:
   pull request lead to less specific changes to the document.
 
 - Leave feedback on Jira cases in the `DOCS
-  <http://jira.mongodb.org/browse/DOCS>`_ project. These are better
+  <http://jira.mongodb.org/browse/DOCS>`__ project. These are better
   for more general changes that aren't necessarily tied to a specific
   line, or affect multiple files.
 

source/practices.txt

@@ -10,4 +10,15 @@ Reference
    Docutils Directives <http://docutils.sourceforge.net/docs/ref/rst/directives.html>
    Sphinx Documentation <http://www.sphinx-doc.org/en/stable/contents.html>
    /redirects
-   /reference/*
+   /reference/apiargs
+   /reference/cond
+   /reference/copyable
+   /reference/eval
+   /reference/icon
+   /reference/lightbox
+   /reference/options
+   /reference/source-constants
+   /reference/suppressing-prevnext-links
+   /reference/template
+   /reference/test-code
+   /reference/xmlrole

source/reference.txt

@@ -1,6 +1,6 @@
-================
-`cond` Directive
-================
+==================
+``cond`` Directive
+==================
 
 The Sphinx built-in ``only`` directive allows writers to
 conditionally include content based on a set of *tags* specified

source/reference/cond.txt

@@ -4,7 +4,7 @@ Copyable Code
 
 Some code blocks are intended for users to copy. The MongoDB theme
 will add a "copy" button to any code block not annotated with the
-`:copyable: false` option.
+``:copyable: false`` option.
 
 Plain rST
 ---------

source/reference/copyable.txt

@@ -46,7 +46,7 @@ This role uses the
 `FontAwesome 5 Solid <https://fontawesome.com/icons?d=gallery&s=solid&m=free>`__
 icon font.
 
-.. icon-fa5-help::
+.. _icon-fa5-help:
 
 Brand Icons (``icon-fa5-brands``)
 ---------------------------------
@@ -55,31 +55,31 @@ This role uses the
 `FontAwesome 5 Brand <https://fontawesome.com/icons?d=gallery&s=brands>`__
 icon font.
 
-.. icon-fa5-brands-help::
+.. _icon-fa5-brands-help:
 
 FontAwesome 4 (``icon-fa4``)
 ----------------------------
 
 This role uses the
 `FontAwesome 4 <https://fontawesome.com/v4.7.0/>`__ icon font.
 
-.. icon-fa4-help::
+.. _icon-fa4-help:
 
 MMS Icons (``icon-mms``)
 ------------------------
 
 This role uses the MMS icon font.
 
-.. icon-mms-help::
+.. _icon-mms-help:
 
 MMS Org (``icon-mms-org``)
 --------------------------
 
 This role uses the MMS Org icon font.
 
-.. icon-mms-org-help::
+.. _icon-mms-org-help:
 
 Charts (``icon-charts``)
 --------------------------
 
-.. icon-charts-help::
+.. _icon-charts-help:

source/reference/icon.txt

@@ -15,9 +15,11 @@ directive if the ``mongodb`` extension is activated in your ``conf.py``.
    .. code-block:: rst
 
       .. figure:: /images/compass-array-query-op.png
+         :alt: lightbox example
          :figwidth: 200px
          :lightbox:
 
    .. figure:: /images/compass-array-query-op.png
+      :alt: lightbox example
       :figwidth: 200px
       :lightbox:

source/reference/lightbox.txt

@@ -55,7 +55,7 @@ Fields
   include file.
 
   This supports documenting ``-o`` and ``-O`` for
-  :binary:`~bin.mongostat`, since MacOS isn't case sensitive and thus
+  ``mongostat``, since MacOS isn't case sensitive and thus
   was overwriting the first option file when generating the second.
 
 - ``args``": The arguments that the option accepts (e.g. ``<host>:<port>``,
@@ -166,7 +166,7 @@ Built-In Variables
   or setting's specified ``program`` (e.g. :binary:`~bin.mongod`).
 
 - ``{{command}}``: automatically replaced by a link to the option or
-  setting's specified ``command`` (e.g. :toolcommand:`record`).
+  setting's specified ``command`` (e.g. ``record``).
 
 Example
 -------