From 697c158ff0d290fe0ce585b9c853b3be260d58c0 Mon Sep 17 00:00:00 2001 From: Paul Wright Date: Sat, 16 Dec 2017 12:51:48 +0000 Subject: [PATCH 1/6] add circleci config --- .circleci/config.yml | 13 +++++++++++++ 1 file changed, 13 insertions(+) create mode 100644 .circleci/config.yml diff --git a/.circleci/config.yml b/.circleci/config.yml new file mode 100644 index 0000000..1301d22 --- /dev/null +++ b/.circleci/config.yml @@ -0,0 +1,13 @@ +version: 2 + +jobs: + build: + docker: + - image: circleci/ruby:2.2-node + working_directory: ~/docs + steps: + - checkout + - run: gem install ascii_binder + - run: asciibinder package + - store_artifacts: + path: ~/docs/_preview From bde135c2eabcba1bb4513f67687621ff5699940e Mon Sep 17 00:00:00 2001 From: Paul Wright Date: Sat, 16 Dec 2017 13:23:27 +0000 Subject: [PATCH 2/6] add quick start --- _topic_map.yml | 7 +++++++ getting_started/index.adoc | 34 ++++++++++++++++++++++++++++++++++ 2 files changed, 41 insertions(+) create mode 100644 getting_started/index.adoc diff --git a/_topic_map.yml b/_topic_map.yml index eb0a0f9..9c3de71 100644 --- a/_topic_map.yml +++ b/_topic_map.yml @@ -29,6 +29,13 @@ Topics: - Name: Philosophy File: philosophy +--- +Name: Getting Started +Dir: getting_started +Topics: + - Name: Quick Start + File: index + --- Name: Guides Dir: guides diff --git a/getting_started/index.adoc b/getting_started/index.adoc new file mode 100644 index 0000000..88217f4 --- /dev/null +++ b/getting_started/index.adoc @@ -0,0 +1,34 @@ += {product-title} {product-version} Getting Started +{product-author} +{product-version} +:data-uri: +:icons: + +This guide provides instructions for getting started with AsciiBinder, enabling you to: + +* Edit an AsciiBinder repo +* Render the results to HTML + +. Fork the link:https://github.com/redhataccess/ascii_binder-docs[ascii_binder_docs] repo. +. Create a directory and add an asciidoc file, for example: ++ +---- +doing_stuff + └── index.adoc +---- +. Edit the asciidoc file to include your content, for example, edit `doing_stuff\index.doc`: ++ +---- += Doing stuff + +It is important to do stuff before you rest. Here are some options: + +* eat +* walk +* talk +---- +. Edit the `_topic_map.yml` file to provide navigation for your new content: ++ +---- + +---- From fe3158e2eff57cc0bc5c484c438d2b19e1c44177 Mon Sep 17 00:00:00 2001 From: Paul Wright Date: Sat, 16 Dec 2017 14:27:48 +0000 Subject: [PATCH 3/6] add quick start --- _topic_map.yml | 3 ++- getting_started/building.adoc | 16 ++++++++++++++++ getting_started/index.adoc | 18 ++++++++++++++++-- 3 files changed, 34 insertions(+), 3 deletions(-) create mode 100644 getting_started/building.adoc diff --git a/_topic_map.yml b/_topic_map.yml index 9c3de71..d7898f4 100644 --- a/_topic_map.yml +++ b/_topic_map.yml @@ -35,7 +35,8 @@ Dir: getting_started Topics: - Name: Quick Start File: index - + - Name: Building a Doc Set + File: building.adoc --- Name: Guides Dir: guides diff --git a/getting_started/building.adoc b/getting_started/building.adoc new file mode 100644 index 0000000..58f68f8 --- /dev/null +++ b/getting_started/building.adoc @@ -0,0 +1,16 @@ += {product-title} {product-version} Building a Doc Set +{product-author} +{product-version} +:data-uri: +:icons: + +Building a doc set involves converting the Asciidoc to HTML using the Asciibinder configuration files. +The following options are outlined in this guide: + +* xref:building-using-ruby[] +* Building using docker +* Building using CI/CD + +[[building-using-ruby]] +== Building Using ruby + diff --git a/getting_started/index.adoc b/getting_started/index.adoc index 88217f4..8505c80 100644 --- a/getting_started/index.adoc +++ b/getting_started/index.adoc @@ -9,6 +9,8 @@ This guide provides instructions for getting started with AsciiBinder, enabling * Edit an AsciiBinder repo * Render the results to HTML +This procedure assumes you are familiar with Asciidoc and git: + . Fork the link:https://github.com/redhataccess/ascii_binder-docs[ascii_binder_docs] repo. . Create a directory and add an asciidoc file, for example: + @@ -21,7 +23,7 @@ doing_stuff ---- = Doing stuff -It is important to do stuff before you rest. Here are some options: +It is important to do stuff every day. Here are some options: * eat * walk @@ -30,5 +32,17 @@ It is important to do stuff before you rest. Here are some options: . Edit the `_topic_map.yml` file to provide navigation for your new content: + ---- - +--- +Name: Doing Stuff +Dir: doing_stuff +Topics: + - Name: Doing Stuff + File: index ---- +. Create an account at link:https://circleci.com/[CirlceCI]. +. Create a CircleCI project pointing at your fork of the ascii_binder_docs repo. +See the link:https://youtu.be/KhjwnTD4oec?t=19s[CircleCI video] for a demostration. +. Push your changes to that repo and CircleCI will automatically create the HTML output. +To see the output HTML, navigate to the artifacts tab of the most recent CircleCI build. + +For more information on building doc sets, including building locally, see xref:building.adoc[Building a Doc Set]. \ No newline at end of file From 55c6c9f6785acc4fc175c5ca56a27dba8ccd3ad4 Mon Sep 17 00:00:00 2001 From: Paul Wright Date: Sat, 16 Dec 2017 14:57:18 +0000 Subject: [PATCH 4/6] add quick start --- getting_started/building.adoc | 42 +++++++++++++++++++++++++++++++---- getting_started/index.adoc | 4 ++-- 2 files changed, 40 insertions(+), 6 deletions(-) diff --git a/getting_started/building.adoc b/getting_started/building.adoc index 58f68f8..cef20fb 100644 --- a/getting_started/building.adoc +++ b/getting_started/building.adoc @@ -1,4 +1,4 @@ -= {product-title} {product-version} Building a Doc Set += Building a Doc Set {product-author} {product-version} :data-uri: @@ -8,9 +8,43 @@ Building a doc set involves converting the Asciidoc to HTML using the Asciibinde The following options are outlined in this guide: * xref:building-using-ruby[] -* Building using docker -* Building using CI/CD +* xref:building-using-docker[] +* xref:building-using-cicd[] [[building-using-ruby]] -== Building Using ruby +== Building Locally Using ruby + +NOTE: Installing ruby 2.2 as required by AsciiBinder may affect existing ruby applications on your system. To avoid issues, use xref:building-using-docker[]. + + + +[[building-using-docker]] +== Building Locally Using Docker + +Docker provides a container based method of building doc sets that only requires the installation of docker, and therefore requires minimal minimal configuration change for your system. + +. Install docker. +. Clone the xref:https://github.com/redhataccess/ascii_binder[ascii_binder] repo. +. Change directory into the repo. +. Enter the following command to create the docker image: ++ +---- +docker build asciibinder:latest . +---- + + +[[building-using-cicd]] +== Building Using CI/CD + +There are many build systems that are used in software including: + +* Jenkins +* Travis CI +* CircleCI + +The Quick Start sectio of this doc set describes how to use CircleCI. That process is controlled by the `.circleci\config.yml` file: +---- +include::..\.circleci\config.yml[] +---- + diff --git a/getting_started/index.adoc b/getting_started/index.adoc index 8505c80..1bff96d 100644 --- a/getting_started/index.adoc +++ b/getting_started/index.adoc @@ -41,8 +41,8 @@ Topics: ---- . Create an account at link:https://circleci.com/[CirlceCI]. . Create a CircleCI project pointing at your fork of the ascii_binder_docs repo. -See the link:https://youtu.be/KhjwnTD4oec?t=19s[CircleCI video] for a demostration. +See the link:https://youtu.be/KhjwnTD4oec?t=19s[CircleCI video] for a demonstration. . Push your changes to that repo and CircleCI will automatically create the HTML output. To see the output HTML, navigate to the artifacts tab of the most recent CircleCI build. -For more information on building doc sets, including building locally, see xref:building.adoc[Building a Doc Set]. \ No newline at end of file +For more information on building doc sets, including building locally, see xref:./building.adoc[Building a Doc Set]. \ No newline at end of file From 6277a262188b19a5b7902679bb42d70c3a1cc91d Mon Sep 17 00:00:00 2001 From: Paul Wright Date: Sat, 16 Dec 2017 18:59:42 +0000 Subject: [PATCH 5/6] add quick start --- _topic_map.yml | 2 +- getting_started/building.adoc | 40 +++++++++++++++++++++++++++++++---- getting_started/index.adoc | 4 ++-- 3 files changed, 39 insertions(+), 7 deletions(-) diff --git a/_topic_map.yml b/_topic_map.yml index d7898f4..78315df 100644 --- a/_topic_map.yml +++ b/_topic_map.yml @@ -36,7 +36,7 @@ Topics: - Name: Quick Start File: index - Name: Building a Doc Set - File: building.adoc + File: building --- Name: Guides Dir: guides diff --git a/getting_started/building.adoc b/getting_started/building.adoc index cef20fb..5ff9e37 100644 --- a/getting_started/building.adoc +++ b/getting_started/building.adoc @@ -1,10 +1,11 @@ +[[building-a-doc-set]] = Building a Doc Set {product-author} {product-version} :data-uri: :icons: -Building a doc set involves converting the Asciidoc to HTML using the Asciibinder configuration files. +Building a doc set involves converting the Asciidoc to HTML using the AsciiBinder configuration files. The following options are outlined in this guide: * xref:building-using-ruby[] @@ -14,7 +15,9 @@ The following options are outlined in this guide: [[building-using-ruby]] == Building Locally Using ruby -NOTE: Installing ruby 2.2 as required by AsciiBinder may affect existing ruby applications on your system. To avoid issues, use xref:building-using-docker[]. +NOTE: Installing a supported version of ruby may affect existing ruby applications on your system. To avoid issues, use xref:building-using-docker[] or use `rvm`. + +See xref:../guides/user_guide.adoc#installing-asciibinder[Installing AsciiBinder] for the steps required to install AsciiBinder. @@ -32,6 +35,20 @@ Docker provides a container based method of building doc sets that only requires docker build asciibinder:latest . ---- +. Change to the docs directory: ++ +---- +cd +---- + +. Use the following command to run the docker container: ++ +---- +docker run -rm -it -v ${PWD}:/docs:z -u $(id -u):$(id -g) asciibinder +---- ++ +The html is generated in the `_preview` directory. + [[building-using-cicd]] == Building Using CI/CD @@ -42,9 +59,24 @@ There are many build systems that are used in software including: * Travis CI * CircleCI -The Quick Start sectio of this doc set describes how to use CircleCI. That process is controlled by the `.circleci\config.yml` file: +The xref:..\getting_started\index.adoc#[Quick Start] page describes how to use CircleCI. That process is controlled by the `.circleci\config.yml` file: ---- -include::..\.circleci\config.yml[] +version: 2 <1> + +jobs: + build: + docker: + - image: circleci/ruby:2.2-node <2> + working_directory: ~/docs + steps: + - checkout + - run: gem install ascii_binder + - run: asciibinder package + - store_artifacts: + path: ~/docs/_preview <3> ---- +<1> You must use CircleCI version 2. +<2> This is the docker image that is used. +<3> This is the output directory that contains the HTML. diff --git a/getting_started/index.adoc b/getting_started/index.adoc index 1bff96d..1b64b03 100644 --- a/getting_started/index.adoc +++ b/getting_started/index.adoc @@ -1,4 +1,4 @@ -= {product-title} {product-version} Getting Started += Getting Started {product-author} {product-version} :data-uri: @@ -45,4 +45,4 @@ See the link:https://youtu.be/KhjwnTD4oec?t=19s[CircleCI video] for a demonstrat . Push your changes to that repo and CircleCI will automatically create the HTML output. To see the output HTML, navigate to the artifacts tab of the most recent CircleCI build. -For more information on building doc sets, including building locally, see xref:./building.adoc[Building a Doc Set]. \ No newline at end of file +For more information on building doc sets, including building locally, see xref:../getting_started/building.adoc#building-a-doc-set[Building a Doc Set]. From 5362fe7e2325a84b948f30a63b374f13f05bd835 Mon Sep 17 00:00:00 2001 From: Paul Wright Date: Wed, 3 Jan 2018 21:47:51 +0000 Subject: [PATCH 6/6] correction to syntax --- getting_started/building.adoc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/getting_started/building.adoc b/getting_started/building.adoc index 5ff9e37..71a5b5d 100644 --- a/getting_started/building.adoc +++ b/getting_started/building.adoc @@ -32,7 +32,7 @@ Docker provides a container based method of building doc sets that only requires . Enter the following command to create the docker image: + ---- -docker build asciibinder:latest . +docker build -t asciibinder:latest . ---- . Change to the docs directory: @@ -44,7 +44,7 @@ cd . Use the following command to run the docker container: + ---- -docker run -rm -it -v ${PWD}:/docs:z -u $(id -u):$(id -g) asciibinder +docker run --rm -it -v ${PWD}:/docs:z -u $(id -u):$(id -g) asciibinder ---- + The html is generated in the `_preview` directory.