/appdev-documentation

Primary LanguageShell

appdev.openshift.io Documentation

This repository holds the documentation for appdev.openshift.io.

Generated docs are built and deployed on every push to the production branch of the authoritative repository (upstream/production) and are available at http://appdev.openshift.io. To test changes before pushing to the production branch, put all forward development in upstream/master and see its current state reflected in the staging environment at http://appdev-stage.openshift.io. The upstream/production branch should typically be updated only via merges from upstream/master when it’s determined the docs are ready to go live.

Directory Structure

  • docs/ - This folder contains all the appdev.openshift.io guides and related content.

    • topics/ - This folder contains adoc files representing shared content between guides.

      • images/ - This folder contains all images used in the guides.

      • styles/ - This folder contains all stylesheets used in the guides.

      • templates/ - This folder contains template data, such as common attributes, used in the guides.

    • GUIDE_NAME/ - There is a folder for each guide.

      • master.adoc - This is the primary file for the guide. Common files or topics are included from the topics/ folder.

      • buildGuide.sh - This is a script to build this individual guide.

      • topics/ - This is a symlink to ../topics/, which makes building each guide a lot easier.

  • scripts/ - This folder contains scripts needed for building guides in the repository.

Building the Guides

  1. Ensure you have AsciiDoctor installed and configured.

  2. Run the scripts/buildGuides.sh script to build all guides.

  3. All guides will be generated as single HTML files in html/.

Contributing

To start contributing:

  1. Fork the upstream repository into your user namespace

  2. Clone your fork.

    $ git clone git@github.com:USERNAME/appdev-documentation.git

  3. Add the main project as a remote.

    $ cd appdev-documentation
$ git remote add upstream git@github.com:openshiftio/appdev-documentation.git
$ git fetch upstream

  4. Create a branch for your contribution based on upstream/master.

    $ git checkout -b my-awesome-idea upstream/master

  5. Make your changes.

  6. Commit your work and push it to your fork.

    $ git add docs/topics/my-awesome-idea.adoc
$ git commit -m "Added my awesome idea."
$ git push origin HEAD

  7. File a pull request to upstream/master.

Add a New Guide

  1. Create a new folder for the guide under docs/ e.g. docs/my-new-guide.

  2. Under that folder:

    • Create a master.adoc file.

    • Create a symlink called topics to ../topics.

      ln -s ../topics topics

    • Copy the buildGuide.sh script from another guide’s folder and modify line 3. This defines the output name of the html file. This should match the folder name.

  3. Add the default content to master.adoc.

    link:topics/templates/document-attributes.adoc[role=include]

:my-new-guide:

= {my-new-guide-guide-name}

  4. Update docs/topics/templates/document-attributes.adoc by adding the guide name attribute.

    :my-new-guide-guide-name: My Awesome New guide

  5. Run the scripts/buildGuides.sh script to ensure the new guide builds with the others.

  6. Open the generated html file to ensure everything looks correct.

You have now created the scaffolding for a new guide. When you are ready for some initial review and feedback, file a pull request to upstream/master.