Merge pull request #128 from ccho-mongodb/PR21-reformatted

PR #21 Reformatted

Author: Chris Cho

snooty.toml

@@ -10,6 +10,15 @@ package-branch = "testing"
 package-version = "4.4.0"
 package-name-org = "mongodb-org"
 version = "4.0"
+rst-title = "reStructuredText"
+rst = "reStructuredText"
+rst-abbrev = "RST"
+yaml = "Yet Another Markup Language"
+yaml-abbrev = "YAML"
+markdown = "Markdown"
+docutils = "Docutils"
+sphinx = "Sphinx"
+docs-platform = "Docs Platform Team"
 
 [substitutions]
 mdbsg = "MongoDB Style Guide"

source/includes/steps-guides.yaml

@@ -238,7 +238,7 @@ content: |
 
         /images-guide
         /tutorials/screencapture-tool
-        /tutorials/tabbed-content
+        /style-guide/markup/directives/tabs
         /tutorials/version-bumping
         /tutorials/generating-a-browser-list
         /error-kb

source/style-guide.txt

@@ -28,6 +28,10 @@ MongoDB external and internal customers.
    Provides advice for using accurate, consistent, and concise
    terminology in your content, and for writing for a global audience.
 
+:doc:`/style-guide/markup-guidelines`
+  Provides detailed guidelines about and instructions for applying
+  {+rst+} ({+rst-abbrev+}) and {+yaml+} ({+yaml-abbrev+}).
+
 :doc:`/style-guide/screenshots/index`
    Provides instructions for when to use and how to create screenshots
    and diagrams to enhance your content.

source/style-guide/includes/terms/s.rst

@@ -144,12 +144,12 @@ S
      .. seealso:: :term:`as`
 
    slash
-     Use *slash* to refer to the / character, and use *backslash* to
-     refer to the \\ character. Don't use :term:`slash mark`.
+     Use *slash* to refer to the ``/`` character, and use *backslash* to
+     refer to the ``\`` character. Don't use *slash mark*.
 
    slash mark
-     :icon-fa5:`trash-alt` Use *slash* to refer to the / character,
-     and use *backslash* to refer to \\ the character.
+     :icon-fa5:`trash-alt` Use *slash* to refer to the ``/`` character,
+     and use *backslash* to refer to ``\\`` the character.
 
    slave
      :icon-fa4:`times-circle` Don't use. Use *secondary* as an

source/style-guide/markup-guidelines.txt

@@ -6,45 +6,40 @@ Markup Guidelines
 
 .. include:: /style-guide/includes/page-needs-update.rst
 
-This section of the style guide provides detailed guidelines about and
-instructions for applying markup conventions for ReStructure Text (RST)
-and MarkDown (MD).
+This section describes markup conventions for {+rst+} ({+rst-abbrev+}) and
+{+markdown+}.
 
-ReStructured Text (RST)
+{+rst-title+} ({+rst-abbrev+})
 ~~~~~~~~~~~~~~~~~~~~~~~
 
-MongoDB documentation uses reStructuredText (RST) markup syntax
+MongoDB documentation uses {+rst+} ({+rst-abbrev+}) markup syntax
 with Sphinx extensions.
 
-RST is a powerful and straightforward markup language that, in
-combination with Sphinx, provides a wide range of facilities for
-intelligent and appealing documentation creation. It uses simple
-and implicit syntax to introduce a variety of content elements such
-as titles, code blocks, vertical lists, and many others. All the
-source content formatted using RST is stored in files with the ``.rst``
-extension.
+See `Introduction to reStructured Text <https://www.writethedocs.org/guide/writing/reStructuredText/>`__ for more information on {+rst-abbrev+}.
 
-For more information on the RST conventions the Information Development
-team follows, see the following resources:
+Parts of {+rst}
+-------------------------
 
-* `OpenStack RST conventions <https://docs.openstack.org/contributor-guide/rst-conv.html>`_.
+Directives
+~~~~~~~~~~
 
-MarkDown (MD)
-~~~~~~~~~~~~~
+A :sphinx-rst:`directive </directives.html?highlight=directive>` specifies a 
+markup block-level element. Block-level elements span the entire width of a row 
+within their container. The directives specify a UI element in which to
+format the associated text or content.
 
-MD is a straightforward markup language that uses simple and implicit
-syntax to introduce a variety of content elements. All the source
-content formatted using MD is stored in files with the ``.md``
-extension.
+Docutils provides the following directives:
 
-To keep the documentation format consistent, follow the guidelines
-included in this chapter for all the MD source content.
+.. code-block:: rst
 
-For more information about MD conventions, see the following
-resources:
+   .. directive::
+
+   :role:
+
+.. toctree::
+   :titlesonly:
+
+   /style-guide/markup/format
+   /style-guide/markup/directives
+   /style-guide/markup/roles
 
-* `Kramdown Quick Reference
-  <https://kramdown.gettalong.org/quickref.html>`_
-* `Kramdown Syntax <https://kramdown.gettalong.org/syntax.html>`_
-* `Markdown Cheatsheet
-  <https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet>`_

source/style-guide/markup/directives.txt

@@ -0,0 +1,35 @@
+==========
+Directives
+==========
+
+Directives provide a means to extend {+rst+} to format blocks of text.
+The markup syntax for directives start with two periods and a space and end
+with two colons as shown in the following example:
+
+.. code-block:: rst
+
+   .. directive::
+
+.. seealso::
+
+   Learn more about directives from the following documentation:
+
+   - :rst:`Docutils Directives </restructuredtext.html#directives>`
+
+   - :sphinx-rst:`Sphinx Directives </basics.html#directives>`
+
+   For a complete list of Snooty directives,
+   see the `Snooty directives toml file <https://github.com/mongodb/snooty-parser/blob/master/snooty/rstspec.toml>`__.
+
+   .. toctree::
+      :titlesonly:
+
+      /style-guide/markup/directives/admonitions
+      /style-guide/markup/directives/conditionals
+      /style-guide/markup/directives/code-blocks
+      /style-guide/markup/directives/content
+      /style-guide/markup/directives/images
+      /style-guide/markup/directives/includes
+      /style-guide/markup/directives/metadata
+      /style-guide/markup/directives/tabs
+      /style-guide/markup/directives/tables

source/style-guide/markup/directives/code-blocks.txt

@@ -0,0 +1,21 @@
+=============
+Code Examples
+=============
+
+As needed, use the appropriate language option for code blocks directives
+including the following directives:
+
+- ``code-block``
+- ``io-code-block``
+- ``literalinclude``
+
+These directives feature syntax highlighting which makes the source code 
+contained in them easier to interpret. The following example shows how to 
+specify Python language syntax highlighting in a ``code-block`` directive:
+
+.. code-block::
+
+   .. code-block:: python
+
+      print("Hello MongoDB") # Python code
+

source/style-guide/markup/directives/metadata.txt

@@ -0,0 +1,28 @@
+========================
+Page Metadata Directives
+========================
+
+meta
+----
+
+Generates HTML ``<meta>`` tags.
+
+.. code-block:: rst
+
+   .. meta::
+
+Learn more about the ``meta`` directive from the
+:rst:`{+docutils+} documentation </directives.html#meta>`.
+
+
+title
+-----
+
+Overrides the document title.
+
+.. code-block:: rst
+
+   .. title::
+
+Learn more about the ``title`` directive from the
+:rst:`{+docutils+} documentation </directives.html#metadata-document-title>`.

source/style-guide/markup/directives/tables.txt

@@ -0,0 +1,13 @@
+================
+Table Directives
+================
+
+Use tables to format related information.
+
+In Snooty, you can use only the ``list-table`` directive to build tables.
+The ``list-table`` directive generates a formatted table from a two-level
+bulleted list.
+
+To learn more about the ``list-table`` directive from the
+`{+docutils+} documentation </directives#list-table>`__.
+

source/tutorials/tabbed-content.txt renamed to source/style-guide/markup/directives/tabs.txt

@@ -1,3 +1,5 @@
+.. _tabbed-content:
+
 ==============
 Tabbed Content
 ==============
@@ -8,39 +10,21 @@ Tabbed Content
    :depth: 2
    :class: singlecol
 
-The tabbed content extension can be used in any MongoDB docs repository
-that uses `docs-tools <https://github.com/mongodb/docs-tools>`_.
-
-Importing the Tabs Extension
-----------------------------
-
-The tabs extension must be imported before it can be used in a docs
-repository. Locate the ``extensions`` array in the desired repository's
-``conf.py`` file and add ``'tabs'`` to the array:
-
-.. code-block:: python
-   :emphasize-lines: 7
+Use the tabbed content directive ``tabs`` to organize information into a
+set of tabs.
 
-   extensions = [
-       'sphinx.ext.extlinks',
-       'sphinx.ext.todo',
-       'mongodb',
-       'directives',
-       'intermanual',
-       'tabs'
-   ]
 
 Choosing a Tab Set
 ------------------
 
 There are two types of directives in the tabs extension:
 
-- :ref:`Pre-defined Tab Sets<pre-defined-tab-set>`: Used for common
+- :ref:`Pre-defined Tab Sets <pre-defined-tab-set>`: Used for common
   groups of tabs that are shared across several pages. Pre-defined
   tab sets do not require the writer to specify the tab's display name
   and also provide error and consistency checking.
 
-- :ref:`Custom Tab Set<custom-tab-set>`: Used for a group of tabs that
+- :ref:`Custom Tab Set <custom-tab-set>`: Used for a group of tabs that
   only apply to a single unique page. Custom tab sets are flexible but
   require the writer to provide the tab's display name and do not offer
   any error or consistency checking.
@@ -101,17 +85,8 @@ all pages that use the same tab set:
 - Eliminate the need for the writer to specify the tab display name
   (tab label)
 
-The following pre-defined tab sets are currently available:
-
-- ``tabs-drivers``
-- ``tabs-platforms``
-- ``tabs-stitch-sdks``
-- ``tabs-stitch-interfaces``
-- ``tabs-auth``
-- ``tabs-deployments``
-
-For detailed information on each tab set, see
-`tabs.py <https://github.com/mongodb/docs-tools/blob/master/sphinxext/tabs.py>`__.
+To find the pre-defined tab sets, see the `Snooty configuration file <https://github.com/mongodb/snooty-parser/blob/master/snooty/rstspec.toml>`__.
+Each entry starts with ``[directive.tabs-``.
 
 Pre-defined tab sets require the following fields for each tab:
 
@@ -173,40 +148,8 @@ code examples stored in different files:
 Defining a New Tab Set
 ~~~~~~~~~~~~~~~~~~~~~~
 
-Create a new tab set if a pre-defined tab set best suits your use case
-but does not exist. New tab sets are defined in the
-``docs-tools/sphinxext/tabs.py`` file.
-
-The following guide walks through creating the ``tabs-platforms``
-directive, the operating systems tab set:
-
-#. Call the methods below and provide a tab set name and an array of
-   tuples in the ``('id', 'displayName')`` format. The following example
-   creates the ``tabs-platforms`` tab set:
-
-   .. code-block:: python
-
-      # Create operating system tab directive
-      app.add_directive('tabs-platforms',
-          create_tab_directive('platforms',
-              [('windows', 'Windows'),
-               ('macos', 'macOS'),
-               ('linux', 'Linux'),
-               ('debian', 'Debian'),
-               ('rhel', 'RHEL')]))
-
-   .. note::
-
-      The first argument to ``create_tab_directive`` should use
-      ``camelCase`` naming. Using hyphens (e.g. ``stitch-sdks`` vs
-      ``stitchSdks``) will cause an error while building.
-
-#. Test changes with a clean build of a docs repo. You must create a
-   symlink from the ``build/docs-tools`` directory to the ``docs-tools``
-   directory containing the changes. Check in the changes and then begin
-   using the new directive on your page.
-
-.. _custom-tab-set:
+To learn more about creating a new pre-defined tab set, contact the
+{+docs-platform+}.
 
 Using a Custom Tab Set
 ~~~~~~~~~~~~~~~~~~~~~~