Skip to content

Creating a New Area

This document contains instructions for creating a new OSG documentation area via GitHub Pages and deploying it automatically with Travis-CI. Before starting, make sure that you have the git and gem tools installed.

  1. Create a new repository in the opensciencegrid organization (referred to as <REPO NAME> in the rest of this document)

    1. Check the box marked Initialize this repository with a README
    2. Once created, add the mkdocs topic by clicking on the "Add topics" button
  2. Clone the repository and cd into the directory:

    git clone [email protected]:opensciencegrid/<REPO NAME>
    cd <REPO NAME>
    
  3. Create a gh-pages branch in the GitHub repository:

    git push origin master:gh-pages
    
  4. Update the contents of README.md and populate the LICENSE file with a Creative Commons Attribution 4.0 license:

    wget https://creativecommons.org/licenses/by/4.0/legalcode.txt > LICENSE
    
  5. Follow these instructions to add the doc-ci-scripts sub-module

  6. Create mkdocs.yml and a docs directory
  7. Create and encrypt the repository deploy key

    1. Generate the repository deploy key:

      ssh-keygen -t rsa -b 4096 -C "[email protected]" -f deploy-key
      
    2. Install the travis gem:

      gem install travis
      
    3. Encrypt the deploy key:

      travis encrypt-file deploy-key
      
    4. Add and commit your files:

      git add LICENSE mkdocs.yml docs deploy-key.enc
      git commit -m "Prepare the repository for Travis-CI deployment"
      

      Danger

      Do NOT commit the unencrypted deploy-key!

    5. Add deploy-key.pub to your repository's list of deploy keys. Make sure to check Allow write access.

  8. Push local changes to the GitHub repository:

    git push origin master
    

    Your documents should be shortly available at https://www.opensciencegrid.org/<REPO NAME>

Creating an ITB Area

This section describes creating an ITB repository for a documentation area created in the previous section

  1. Create a new repository in the opensciencegrid organization and name it <REPO NAME>-itb. For example, an ITB area for the docs repository has a repository name of docs-itb. The ITB repository will be referred to as <ITB REPO NAME> in the rest of this document.

    1. Check the box marked Initialize this repository with a README
    2. Once created, add the mkdocs topic by clicking on the "Add topics" button
  2. Clone the repository and cd into the directory:

    git clone [email protected]:opensciencegrid/<ITB REPO NAME>
    cd <ITB REPO NAME>
    
  3. Create a gh-pages branch in the GitHub repository:

    git push origin master:gh-pages
    
  4. Update the contents of README.md

  5. In the non-ITB repository, create and encrypt the ITB repository deploy key

    1. cd into the non-ITB repository and generate the ITB deploy key

      cd <REPO NAME>
      ssh-keygen -t rsa -b 4096 -C "[email protected]" -f deploy-itb
      
    2. Install the travis gem:

      gem install travis
      
    3. Encrypt the deploy key:

      travis encrypt-file deploy-itb
      
    4. Update .travis.env with the appropriate ITB values

    5. Add and commit your files:

      git add .travis.env deploy-itb.enc
      git commit -m "Add ITB deployment"
      

      Danger

      Do NOT commit the unencrypted deploy-itb!

  6. Add deploy-itb.pub to the ITB repository's list of deploy keys. Make sure to check Allow write access.

  7. Still in the non-ITB repository, push your local changes to the GitHub repository

    git push origin master
    

    Your documents should be shortly available at https://www.opensciencegrid.org/<REPO NAME>