Merge pull request #11 from skerschb/DOCSP-4830

docstools-enabled repo tutorial

Author: skerschb

source/includes/steps-repo.yaml

@@ -0,0 +1,216 @@
+title: "Clone a repo similar to the repository you wish to create."
+ref: clone-repo
+content: |
+  
+  First, clone a repository that is similar to the repository you wish to create.
+
+  For this example, we will clone the docs-meta repository. Clone the repo to the name you wish to give your new repo.
+ 
+  .. code-block:: sh
+     
+     git clone [email protected]:mongodb/docs-meta.git <docs-yourrepo>
+
+
+  Run:
+
+  .. code-block:: sh
+     
+     cd <docs-yourrepo>
+
+---
+title: Delete the .git directory
+ref: delete-git 
+content: |
+
+  
+
+  Delete the .git directory in your local, cloned version of the repository so that you can begin with your own repository.
+
+  .. code-block:: sh 
+   
+     rm -rf .git
+
+  Check to make sure you have deleted the .git file:
+
+  .. code-block:: sh
+
+     git branch
+    
+  You should see the following error:
+
+  .. code-block:: sh
+     :copyable: false
+
+     fatal: Not a git repository (or any of the parent directories): .git
+
+     
+---
+title: Check to make sure you have removed the .git directory
+ref: check-rm
+content: |
+  Before you proceed, check to make sure that .git directory is gone by running ls:
+
+  .. code-block:: sh
+
+     ls -al
+
+  Your output should be something like:
+
+  .. code-block:: sh
+     :copyable: false
+
+     total 32
+     drwxr-xr-x   7 you  staff   238 Mar 11 05:05 .
+     drwxr-xr-x  85 you  staff  2890 Mar 11 05:02 ..
+     -rw-r--r--   1 you  staff  2424 Mar 11 05:02 .gitignore 
+     -rw-r--r--   1 you  staff  2243 Mar 11 05:02 Makefile
+     -rw-r--r--   1 you  staff  7087 Mar 11 05:02 conf.py
+     drwxr-xr-x   8 you  staff   272 Mar 11 05:02 config
+     drwxr-xr-x  17 you  staff   578 Mar 11 05:02 source
+  
+---
+title: Reinitialize the repo
+ref: git-reinit
+content: |
+  Run git init to reinitialize the repo:
+
+  .. code-block:: sh
+ 
+     git init
+
+  You will see the following output:
+
+  .. code-block:: sh 
+     :copyable: false
+
+     Initialized empty Git repository in <yourdirectorystructure>/docs-yourrepo/.git/
+
+  Check your work:
+
+  .. code-block:: sh
+
+     ls -al
+
+  The new .git directory should now appear.
+
+---
+title: Create the repository on GitHub
+ref: create-repo
+content: |
+
+  Create the repo you would like to use on GitHub.
+
+  You will then need to commit some files and add your local repository to github. If you add all of the files, you will
+  nned to remove the ones that are not relevant to your repository later, but this is a perfectly acceptable way to start your repository.
+
+  Make sure you add a README.md file to your repo. Add a sentence to the file to describe your project. Then save the file and run:
+
+  .. code-block:: sh
+
+     git add README.md
+     git commit -m "first commit"
+     git remote add origin [email protected]:mongodb/docs-yourrepo.git
+     git push -u origin master
+
+---
+
+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>`_.
+
+  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.
+
+  Add the origin remote for your forked repo:
+
+  .. code-block:: sh
+     
+     git remote add origin https://github.com/<fork>/docs-yourrepo
+
+  Add the upstream remote:
+
+  .. code-block:: sh
+
+     git remote add upstream https://github.com/<repoOwner>/<remoteRepoRoot>.git
+
+---
+title: Edit conf.py
+ref: edit-confpy 
+content: |
+
+  Edit the conf.py as needed. ``conf.py`` is where you can add sphinx extensions and roles that you might require for your docs.
+
+  If you'd like to accept the default ``conf.py``, that's fine too.
+
+---
+title: Edit config/sphinx_local.yaml
+ref: edit-local
+content: |
+
+  In this ``config/sphinx_local.yaml`` file, you will want to change the name of the project:
+
+  .. code-block:: sh
+
+     project: 'mongodb-<yoursitename>'
+
+---
+
+title: Edit config/build_conf.yaml
+ref: edit-buildconf
+content: |
+
+  In order to make sure that your builds go to the right location on staging and production, modify the ``config/build_conf.yaml`` file.
+
+  - Modify the git/remote section to reflect your repository.
+  - Modify the project name to match the name of your project.
+  - Modify the url and tag in the project section.
+
+  .. code-block:: sh
+     :copyable: false
+
+     git:
+       remote:
+         upstream: 'mongodb/docs-yourrepo'
+         tools: 'mongodb/docs-tools'
+     project:
+       name: 'yourprojectname'
+       tag: 'ypt'
+       url: 'https://docs.mongodb.com/projectname'
+       title: 'MongoDB Project Documentation'
+       branched: false
+
+  
+---
+title: Install Build Tools
+ref: install-build
+content: |
+
+  You will need to `install the build tools <https://gist.github.com/atsansone/aa6b793da9ca30fe7d46#install-the-documentation-software>`_ in order to build your repository.
+
+  Once you have installed the build tools, you can attempt to build your repository.
+
+---
+title: Running a Build Locally
+ref: run-build
+content: |
+
+  If you are simply planning to build locally, you can build your repository by running:
+
+  .. code-block:: sh
+
+     make html
+
+  You will see output pertaining to your build in the ``build/<branch>`` directory local to your repository.
+
+---
+title: Deploying Your Site
+ref: edit-makefile
+content: |
+
+  If you wish to deploy your site to ``mongodb.com`` and leverage the existing staging servers. you will `need to request a token 
+  <https://gist.github.com/atsansone/aa6b793da9ca30fe7d46#systems-authentication-and-authorization>`_ to be able to publish to the S3 buckets.
+
+  Modify the fields in the Makefile that pertain to the location of your deployed site if you wish to do so.
+
+...

source/tutorials.txt

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

source/tutorials/repo.txt

@@ -0,0 +1,23 @@
+.. guide::
+   title: How to Create a Docstools-Enabled Repository 
+   author: MongoDB Documentation Team
+   type: Deep Dive 
+   level: intermediate 
+   product_version: 4.0
+   result_description:
+     In this guide you will learn how to create a docstools-enabled repository.
+   time: 45
+   prerequisites:
+     - access to git
+   check_your_environment:
+     - check to make sure you have git installed
+   procedure:
+     .. include:: /includes/steps/repo.rst
+   summary:
+     If you have successfully completed this guide, you have 
+     created a MongoDB docstools-enabled repository. 
+   whats_next:
+     Congratulations! Now that you've created your repository, you can create your docstools-enabled content.
+   seealso:
+     - `check out the guides site for examples <http://docs.mongodb.com/guides>`__.
+     - :doc:`Tabbed Content Tutorial </tutorials/tabbed-content>`