Skip to content

Commit

Permalink
Added support of readme generation (#35)
Browse files Browse the repository at this point in the history 
* Added support of readme generation

* Simplify docs gen

* Made pluggable architecture and one command generation

* Remove trunl

* Fix README template

* Fix README

* Fix README

* Redo doc generate to bash script

* Make all dynamic datasources be in tmp dir

* Address comments

* Made wordwrap for terraform tables

* Remove wordwrap

* Address comments
  • Loading branch information
@goruha
goruha authored Dec 8, 2017
1 parent dce4682 commit dbd0e31
Show file tree
Hide file tree
Showing 22 changed files with 531 additions and 73 deletions.
54 changes: 54 additions & 0 deletions .README.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,54 @@
# Cloud Posse Build Harness [![Build Status](https://travis-ci.org/cloudposse/build-harness.svg)](https://travis-ci.org/cloudposse/build-harness)
{{ (datasource "section").warning }}

This `build-harness` is a collection of Makefiles to facilitate building Golang projects, Dockerfiles, Helm charts, and more.

It's designed to work with CI/CD systems such as Travis CI, CircleCI and Jenkins.

It's 100% Open Source and licensed under [APACHE2](LICENSE).


## Usage

At the top of your `Makefile` add, the following...

```make
-include $(shell curl -sSL -o .build-harness "https://git.io/build-harness"; echo .build-harness)
```

This will download a `Makefile` called `.build-harness` and include it at run-time. We recommend adding the `.build-harness` file to your `.gitignore`.

This automatically exposes many new targets that you can leverage throughout your build & CI/CD process.

Run `make help` for a list of available targets.

{{ (datasource "make").help }}

## Real World Examples

- [`github-authorized-keys`](https://github.com/cloudposse/github-authorized-keys/) - A Golang project that leverages `docker:%`, `go:%`, `travis:%` targets
- [`charts`](https://github.com/cloudposse/charts/) - A collection of Helm Charts that leverages `docker:%` and `helm:%` targets
- [`bastion`](https://github.com/cloudposse/bastion/) - A docker image that leverages `docker:%` and `bash:lint` targets
- [`terraform-null-label`](https://github.com/cloudposse/terraform-null-label/) - A terraform module that leverages `terraform:%` targets

{{ (datasource "section").help }}
{{ (datasource "section").contributing }}

Here's how to get started...

1. `git clone https://github.com/cloudposse/{{ (datasource "git").name }}.git` to pull down the repository
2. `make init` to initialize the [`{{ (datasource "git").name }}`](https://github.com/cloudposse/{{ (datasource "git").name }}/)
3. Review the [documentation](docs/) on compiling


{{ (datasource "license").apache2 }}
{{ (datasource "section").about }}

### Contributors

|
{{- (datasource "contributor").erik }} |
{{- (datasource "contributor").igor }} |
|---|---|

{{ (datasource "contributor")._links }}
1 change: 1 addition & 0 deletions .gitignore
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
./terraform
8 changes: 4 additions & 4 deletions Makefile
View file
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
BUILD_HARNESS_PATH ?= .
OS ?= $(shell uname -s | tr '[:upper:]' '[:lower:]')
SELF ?= make
export BUILD_HARNESS_PATH ?= $(shell 'pwd')
export OS ?= $(shell uname -s | tr '[:upper:]' '[:lower:]')
export SELF ?= make

include $(BUILD_HARNESS_PATH)/Makefile.*
include $(BUILD_HARNESS_PATH)/modules/*/*
include $(BUILD_HARNESS_PATH)/modules/*/Makefile*
146 changes: 84 additions & 62 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,6 +1,10 @@
# Cloud Posse Build Harness [![Build Status](https://travis-ci.org/cloudposse/build-harness.svg)](https://travis-ci.org/cloudposse/build-harness)
<!---
--- This file was automatically generated by the `build-harness`
--- Make changes instead to `.README.md` and rebuild.
--->

This `build-harness` is a collection of Makefiles to facilitate building Golang projects, Dockerfiles, Helm charts, and more.
This `build-harness` is a collection of Makefiles to facilitate building Golang projects, Dockerfiles, Helm charts, and more.

It's designed to work with CI/CD systems such as Travis CI, CircleCI and Jenkins.

Expand All @@ -21,57 +25,60 @@ This automatically exposes many new targets that you can leverage throughout you

Run `make help` for a list of available targets.


## Makefile Targets

```bash
$ make help

Available targets:

bash:lint Lint all bash scripts
docker:build Build docker image
docker:login Login into docker hub
docs:copyright-add Add copyright headers to source code
docs:toc-update Update table of contents in README.md
geodesic:deploy Run a Jenkins Job to Deploy $(APP) with $(CANONICAL_TAG)
git:aliases-update Update git aliases
git:submodules-update Update submodules
github:download-private-release Download release from github
github:download-public-release Download release from github
go:build Build binary
go:build-all Build binary for all platforms
go:clean Clean compiled binary
go:clean-all Clean compiled binary and dependency
go:deps Install dependencies
go:deps-build Install dependencies for build
go:deps-dev Install development dependencies
go:fmt Format code according to Golang convention
go:install Install cli
go:lint Lint code
go:test Run tests
go:vet Vet code
helm:install Install helm
helm:repo:add-current Add helm remote dev repos
helm:repo:add-remote Add helm remote repos
helm:repo:build Build repo
helm:repo:clean Clean helm repo
helm:repo:fix-perms Fix repo filesystem permissions
helm:repo:info Show repo info
helm:repo:lint Lint charts
helm:serve:index Build index for serve helm charts
help This help screen
jenkins:run-job-with-tag Run a Jenkins Job with $(TAG)
make:lint Lint all makefiles
terraform:get-modules Ensure all modules can be fetched
terraform:get-plugins Ensure all plugins can be fetched
terraform:lint Lint check Terraform
terraform:validate Basic terraform sanity check
travis:docker-login Login into docker hub
travis:docker-tag-and-push Tag & Push according Travis environment variables
Available targets:

bash:lint Lint all bash scripts
docker:build Build docker image
docker:login Login into docker hub
docs:build Create $OUT file by building it from $IN template file
docs:copyright-add Add copyright headers to source code
docs:deps Install dependencies
geodesic:deploy Run a Jenkins Job to Deploy $(APP) with $(CANONICAL_TAG)
git:aliases-update Update git aliases
github:download-private-release Download release from github
github:download-public-release Download release from github
git:submodules-update Update submodules
go:build Build binary
go:build-all Build binary for all platforms
go:clean Clean compiled binary
go:clean-all Clean compiled binary and dependency
go:deps Install dependencies
go:deps-build Install dependencies for build
go:deps-dev Install development dependencies
go:fmt Format code according to Golang convention
go:install Install cli
go:lint Lint code
go:test Run tests
go:vet Vet code
helm:install Install helm
helm:repo:add-current Add helm remote dev repos
helm:repo:add-remote Add helm remote repos
helm:repo:build Build repo
helm:repo:clean Clean helm repo
helm:repo:fix-perms Fix repo filesystem permissions
helm:repo:info Show repo info
helm:repo:lint Lint charts
helm:serve:index Build index for serve helm charts
help This help screen
jenkins:run-job-with-tag Run a Jenkins Job with $(TAG)
make:lint Lint all makefiles
readme:build Create README.md by building it from .README.md file
readme:init Create basic minimalistic .README.md template file
readme:toc-update Update table of contents in README.md
terraform:get-modules Ensure all modules can be fetched
terraform:get-plugins Ensure all plugins can be fetched
terraform:install Install terraform
terraform:lint Lint check Terraform
terraform:validate Basic terraform sanity check
travis:docker-login Login into docker hub
travis:docker-tag-and-push Tag & Push according Travis environment variables
```


## Real World Examples

- [`github-authorized-keys`](https://github.com/cloudposse/github-authorized-keys/) - A Golang project that leverages `docker:%`, `go:%`, `travis:%` targets
Expand All @@ -81,10 +88,9 @@ Available targets:

## Help

**Got a question?**
**Got a question?**

File a GitHub [issue](https://github.com/cloudposse/build-harness/issues), send us an [email](mailto:[email protected]) or reach out to us on [Gitter](https://gitter.im/cloudposse/).

## Contributing

### Bug Reports & Feature Requests
Expand All @@ -93,7 +99,7 @@ Please use the [issue tracker](https://github.com/cloudposse/build-harness/issue

### Developing

If you are interested in being a contributor and want to get involved in developing the `build-harness`, we would love to hear from you! Shoot us an [email](mailto:[email protected]).
If you are interested in being a contributor and want to get involved in developing `build-harness`, we would love to hear from you! Shoot us an [email](mailto:[email protected]).

In general, PRs are welcome. We follow the typical "fork-and-pull" Git workflow.

Expand All @@ -107,13 +113,16 @@ In general, PRs are welcome. We follow the typical "fork-and-pull" Git workflow.

Here's how to get started...

1. `git clone https://github.com/cloudposse/build-harness.git` to pull down the repository
1. `git clone https://github.com/cloudposse/build-harness.git` to pull down the repository
2. `make init` to initialize the [`build-harness`](https://github.com/cloudposse/build-harness/)
3. Review the [documentation](docs/) on compiling


## License

[APACHE 2.0](LICENSE) © 2016-2017 [Cloud Posse, LLC](https://cloudposse.com)
[APACHE 2.0](LICENSE) © 2017 [Cloud Posse, LLC](https://cloudposse.com)

See [LICENSE](LICENSE) for full details.

Licensed to the Apache Software Foundation (ASF) under one
or more contributor license agreements. See the NOTICE file
Expand All @@ -122,7 +131,7 @@ Here's how to get started...
to you under the Apache License, Version 2.0 (the
"License"); you may not use this file except in compliance
with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing,
Expand All @@ -131,28 +140,41 @@ Here's how to get started...
KIND, either express or implied. See the License for the
specific language governing permissions and limitations
under the License.

## About

GitHub Authorized Keys is maintained and funded by [Cloud Posse, LLC][website]. Like it? Please let us know at <[email protected]>
This project is maintained and funded by [Cloud Posse, LLC][website]. Like it? Please let us know at <[email protected]>

We love [Open Source Software](https://github.com/cloudposse/)!
We love [Open Source Software](https://github.com/cloudposse/)!

See [our other projects][community] or [hire us][hire] to help build your next cloud-platform.
See [our other projects][community]
or [hire us][hire] to help build your next cloud-platform.

[website]: http://cloudposse.com/
[community]: https://github.com/cloudposse/
[hire]: http://cloudposse.com/contact/

### Contributors

|[![Erik Osterman][erik_img]][erik_web]<br/>[Erik Osterman][erik_web] |[![Igor Rodionov][igor_img]][igor_web]<br/>[Igor Rodionov][igor_img] |
|---|---|

[andriy_img]: https://avatars0.githubusercontent.com/u/7356997?v=4&u=ed9ce1c9151d552d985bdf5546772e14ef7ab617&s=144
[andriy_web]: https://github.com/aknysh/

[erik_img]: http://s.gravatar.com/avatar/88c480d4f73b813904e00a5695a454cb?s=144
[erik_web]: https://github.com/osterman/

[igor_img]: http://s.gravatar.com/avatar/bc70834d32ed4517568a1feb0b9be7e2?s=144
[igor_web]: https://github.com/goruha/

| [![Erik Osterman][erik_img]][erik_web]<br/>[Erik Osterman][erik_web] | [![Igor Rodionov][igor_img]][igor_web]<br/>[Igor Rodionov][igor_web] |
|-------------------------------------------------------|------------------------------------------------------------------|
[konstantin_img]: https://avatars1.githubusercontent.com/u/11299538?v=4&u=ed9ce1c9151d552d985bdf5546772e14ef7ab617&s=144
[konstantin_web]: https://github.com/comeanother/

[erik_img]: http://s.gravatar.com/avatar/88c480d4f73b813904e00a5695a454cb?s=144
[erik_web]: https://github.com/osterman/
[igor_img]: http://s.gravatar.com/avatar/bc70834d32ed4517568a1feb0b9be7e2?s=144
[igor_web]: https://github.com/goruha/
[sergey_img]: https://avatars1.githubusercontent.com/u/1134449?v=4&u=ed9ce1c9151d552d985bdf5546772e14ef7ab617&s=144
[sergey_web]: https://github.com/s2504s/

[valeriy_img]: https://avatars1.githubusercontent.com/u/10601658?v=4&u=ed9ce1c9151d552d985bdf5546772e14ef7ab617&s=144
[valeriy_web]: https://github.com/drama17/

[vladimir_img]: https://avatars1.githubusercontent.com/u/26582191?v=4&u=ed9ce1c9151d552d985bdf5546772e14ef7ab617&s=144
[vladimir_web]: https://github.com/SweetOps/
91 changes: 91 additions & 0 deletions bin/doc_generate.sh
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,91 @@
#!/usr/bin/env bash

IN=${IN:-".README.md"}
OUT=${OUT:-"README.md"}

TIMESTAMP=$(date +"%s")
TMP=/tmp/$TIMESTAMP

mkdir -p $TMP

declare -A DATASOURCES

INCLUDED_MODULES=()

# Merge 2 lists (in format words separated be space in string)
function array-merge {
# Declare an associative array
declare -A tmp
# Store the values of arr3 in arr4 as keys.
for k in $@; do tmp["$k"]=1; done
# Extract the keys.
echo "${!tmp[@]}"
}

## Get template docs modules from $IN file
## Example of usage
## module ./.README.md
function modules {
grep -oP "(?<=datasource)\s+\".*?\"" $1 | sed 's/[ |\"]//g' | sort | uniq | paste -sd " " -
}

## Fire event $1 for all modules passed as args
## Example of usage
## fire event "test" "git" "make"
## Will call functions "git-test" and "make-test" if exists
function fire_event {
local event=$1
local modules=${@:2}

for module in $modules
do
func="$module-$event"
if [ "$(type -t $func)" = 'function' ]; then
$func
fi
done
}

## Provde datasource options for modules passed as args
## Example of usage
## datasources "git" "make"
function datasources {
for k in $@; do
echo "--datasource $k=${DATASOURCES[$k]}"
done
}

## Register modules
for file in $BUILD_HARNESS_PATH/modules/*/docs/*.sh ; do
if [ -f "$file" ] ; then
. "$file"
fi
done

## Find used modules in $IN file
MODULES=$(modules $IN)

until [ -z "$MODULES" ]
do
## Merge modules list with modules from previous iteration
INCLUDED_MODULES=$( array-merge $INCLUDED_MODULES $MODULES)
## Prepare data for just found modules
fire_event "docs-prepare-data" $MODULES
## Replace template
$GOMPLATE --file $IN --out $OUT $(datasources $INCLUDED_MODULES)

## For all iterations (except first) use $OUT file as $IN template to replace recursive placeholders
IN=$OUT
## Find modules in $IN file for next interation.
MODULES=$(modules $IN)
done

## Cleanup prepared data for all used modules
fire_event "docs-cleanup-data" $INCLUDED_MODULES

rm -rf $TMP

echo "$OUT doc generated"



Loading

0 comments on commit dbd0e31

Please sign in to comment.