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.
-
docs/- This folder contains all the appdev.openshift.io guides and related content.-
topics/- This folder containsadocfiles 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 thetopics/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.
-
Ensure you have AsciiDoctor installed and configured.
-
Run the
scripts/buildGuides.shscript to build all guides. -
All guides will be generated as single HTML files in
html/.
To start contributing:
-
Fork the upstream repository into your user namespace
-
Clone your fork.
$ git clone [email protected]:USERNAME/appdev-documentation.git -
Add the main project as a remote.
$ cd appdev-documentation $ git remote add upstream [email protected]:openshiftio/appdev-documentation.git $ git fetch upstream -
Create a branch for your contribution based on
upstream/master.$ git checkout -b my-awesome-idea upstream/master -
Make your changes.
-
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 -
File a pull request to
upstream/master.
-
Create a new folder for the guide under
docs/e.g.docs/my-new-guide. -
Under that folder:
-
Create a
master.adocfile. -
Create a symlink called
topicsto../topics.ln -s ../topics topics -
Copy the
buildGuide.shscript from another guide’s folder and modify line 3. This defines the output name of the html file. This should match the folder name.
-
-
Add the default content to master.adoc.
link:topics/templates/document-attributes.adoc[role=include] :my-new-guide: = {my-new-guide-guide-name} -
Update
docs/topics/templates/document-attributes.adocby adding the guide name attribute.:my-new-guide-guide-name: My Awesome New guide -
Run the
scripts/buildGuides.shscript to ensure the new guide builds with the others. -
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.