Merge pull request #8 from skerschb/DOCSP-3254

This is the actual guides guide.

Author: skerschb

conf.py

@@ -41,7 +41,8 @@ def has(self, *args):
     'testcode',
     'tabs',
     'icon',
-    'xmlrole'
+    'xmlrole',
+    'guides'
 ]
 
 locale_dirs = [ os.path.join(conf.paths.projectroot, conf.paths.locale) ]

source/includes/steps-guides.yaml

@@ -0,0 +1,237 @@
+title: "Add guides to your sphinx extensions."
+ref: add-guides
+content: |
+  Add 'guides' to the extensions list in conf.py in your repo root.
+ 
+  .. code-block:: sh
+     
+     extensions = [
+     'sphinx.ext.extlinks',
+     'sphinx.ext.todo',
+     'mongodb',
+     'directives',
+     'intermanual',
+     'testcode',
+     'tabs',
+     'markdown',
+     'fasthtml',
+     'source_constants',
+     'icon'
+     'guides'
+     ]  
+---
+title: Copy the guides directive template into a file in your repo. 
+ref: copy-guide 
+content: |
+  Copy the following directive template into a file to begin
+  writing your guide. Make sure it's under the source directory and
+  give it a .txt extension. Otherwise it won't build.
+
+  .. note::
+  
+     While the spacing makes this example look a bit like a .yaml
+     file, it's really a sphinx directive. This guide should compile as-is.
+
+  .. code-block:: sh 
+
+     .. guide::  
+        title: This is your guide title 
+        author: MongoDB Documentation Team
+        type: Getting Started 
+        level: beginner
+        product_version: 4.0
+        languages:
+          shell
+          compass
+          python
+          java-sync
+          nodejs
+          motor
+          csharp
+        result_description:
+          This is a handy description of the result you will achieve
+          if you successfully create this guide. 
+        time: 15 
+        prerequisites:
+          - first do this guide 
+          - then do this one 
+          - make sure you have installed some stuff
+        check_your_environment:
+          Check to see if your environment has everything it needs.
+          List things you need to complete this guide
+            - binaries installed
+            - permissions
+            - drivers or libraries 
+        procedure:
+          Feel free to put the steps include here.
+          
+          At the moment, tabbed content does not display properly when put
+          directly in the procedure section. Use an include file for tabbed
+          content. 
+        summary:
+          Congrats! You accomplished something. 
+        whats_next:
+          - check out the `guide on such and such </guide/such-and-such>`
+
+---
+title: Fill in your guide template
+ref: make-template
+content: |
+  Now it's time to fill in the fields in the template to create your guide.
+
+  The languages section is optional, so use it only if you would like
+  pills at the top of your page and have tabbed language content
+  (tabs-drivers) to toggle.
+
+  The following sections are required:
+   .. list-table::
+      :header-rows: 1
+      :widths: auto
+      :class: guide-tablenate 
+     
+      * - field
+        - type   
+        - possible values
+
+      * - title
+        - string
+        - any
+
+      * - author  
+        - string
+        - any
+
+      * - level
+        - string
+        - beginner, intermediate, advanced
+
+      * - time
+        - number  
+        - any
+ 
+      * - type
+        - string
+        - Getting Started, Use Case, Deep Dive
+ 
+      * - product_version
+        - number
+        - any
+
+      * - prerequisites
+        - text     
+        - any
+     
+      * - summary
+        - text
+        - any
+    
+      * - procedure
+        - text    
+        - any
+     
+      * - result_description
+        - text
+        - any
+---
+title: Document the content with steps required to complete the tutorial 
+ref: make-steps 
+content: |
+  Document the steps required for your guide. If you'd like content
+  with numbered steps, use a step file.
+ 
+  Step files are *.yaml* files that get converted during the build process
+  to *.rst* files and
+  are included as `/<dir>/steps/<something>.rst`. When you create the .yaml
+  step file, name it according to the convention:
+
+  .. note::
+     
+     Guides use headings to delineate sections. If you would like to provide
+     subsections for your guides sections, use subheadings.
+
+  
+  .. code-block:: sh
+ 
+     <dir>/steps-<something>.yaml
+
+  Here is an example of a .yaml steps file. Notice that you can
+  nest includes within the step content if you wish.
+
+  .. code-block:: sh 
+     
+     title: Find the ``mongo`` Shell
+     ref: mongo-shell
+     content: |
+
+       The ``mongo`` shell is packaged with the MongoDB Server
+       Community and Enterprise distributions, and is also available
+       for users of Atlas as a client-only download.
+
+       If you do not have ``mongo`` shell installed, follow the
+       install directions for your environment.
+
+       .. include:: /includes/download-shell-tabs.rst
+
+     ---
+
+     title: Connect to your MongoDB instance
+     ref: connect
+     content: |
+
+       .. include:: /includes/mongo-shell-platform-connect-np.rst
+
+---
+title: Add What's Next and See Also (optional) sections
+ref: whats-next 
+content: |
+
+  The *What's Next* and *See Also* sections are important for
+  leading the reader to the next step in their learning.
+
+  Add links to other tutorials in the *What's Next* section and
+  save *See Also* for content that links out of the tutorial format
+  such as in-depth manual content and reference material.
+
+  If you have `:manual:` in your conf.py as an extlink map, you can use:
+
+  .. code-block:: sh
+
+     :manual:`short description </reference/blah>`
+
+  Or for content that lives in your own repo, feel free to use:
+
+  .. code-block:: sh
+
+     :doc:`Some Local Content </localdir/localcontent>`
+
+  External links or links referenced from outside of a repo with shortcuts configured
+  can be referenced using the fully qualified url:
+
+  .. code-block:: sh
+     
+     `Site to link to <http://fully.qualified.domain/stuff>`__.
+
+---
+title: Add the Guide to a Table of Contents
+ref: add-to-toc 
+content: |
+
+  To add the guide to a table of contents, use the same method you would
+  use for any standard docs content.
+
+  In the .txt file for the TOC in question, add the link.
+
+  .. code-block:: none 
+
+     .. toctree::
+        :titlesonly:
+
+        /images-guide
+        /tutorials/screencapture-tool
+        /tutorials/tabbed-content
+        /tutorials/version-bumping
+        /tutorials/generating-a-browser-list
+        /error-kb
+        /tutorials/guide
+
+...

source/tutorials.txt

@@ -11,3 +11,4 @@ Tutorials
    /tutorials/version-bumping
    /tutorials/generating-a-browser-list
    /error-kb
+   /tutorials/guide

source/tutorials/guide.txt

@@ -0,0 +1,26 @@
+.. guide::
+   title: How to Create a Guide for MongoDB Docs 
+   author: MongoDB Documentation Team
+   type: Deep Dive 
+   level: intermediate 
+   product_version: 4.0
+   result_description:
+     In this guide you will create a MongoDB Guide.
+   time: 45
+   prerequisites:
+     - a docs repository that leverages docs-tools
+     - content for the guide
+   check_your_environment:
+     - check for the conf.py script in your repository root 
+       (you'll need this if you want to compile a guide)
+   procedure:
+     .. include:: /includes/steps/guides.rst
+   summary:
+     If you have successfully completed this guide, you have 
+     created a MongoDB guide and added it to your table of contents. 
+   whats_next:
+     Congratulations! You've reached the end of this one part
+     series on creating guides!
+   seealso:
+     - `check out the guides site for examples <http://docs.mongodb.com/guides>`__.
+     - :doc:`Tabbed Content Tutorial </tutorials/tabbed-content>`