Skip to content

Creating a New Area

This document contains instructions for creating a new top-level OSG website via GitHub Pages and deploying it automatically with Travis-CI. This document assumes that you are an administrator of the opensciencegrid GitHub organization. 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. Identify the repository as using mkdocs:

    1. On the repository home page (i.e., https://github.com/opensciencegrid/<REPO NAME>), click the “Manage topics” link
    2. Search for mkdocs and select mkdocs
    3. Click the “Done” button
  3. Clone the repository and cd into the directory:

    git clone https://github.com/opensciencegrid/<REPO NAME>.git
    cd <REPO NAME>
    
  4. Create a gh-pages branch in the GitHub repository:

    git push origin master:gh-pages
    
  5. 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
    
  6. 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 -N ''
      
    2. Install the travis gem:

      gem install travis
      
    3. Login using your GitHub credentials:

      travis login
      
    4. Enable the repository in Travis:

      travis enable opensciencegrid/<REPO NAME>
      
    5. Encrypt the deploy key:

      travis encrypt-file deploy-key
      
    6. Stage and commit your files:

      git add LICENSE README.md deploy-key.enc
      git commit -m "Prepare the repository for Travis-CI deployment"
      

      Danger

      Do NOT commit the unencrypted deploy-key!

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

  7. Follow these instructions to add the doc-ci-scripts sub-module

  8. Create mkdocs.yml containing the following:

    site_name: <TITLE OF YOUR SITE>
    site_url: https://opensciencegrid.org/<REPO NAME>
    repo_name: https://github.com/opensciencegrid/<REPO NAME>
    
    pages:
      - Home: 'index.md'
    
    markdown_extensions:
      - admonition
      - codehilite:
          guess_lang: False
      - toc:
          permalink: True
    
  9. Create a docs directory containing an index.md that will be your home page.

  10. Stage and commit these changes:

    git add mkdocs.yml docs/index.md
    git commit -m "Staging initial web page contents"
    
  11. 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>