Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Implement new readme generator #61

Merged
merged 40 commits into from
Jun 18, 2018
Merged

Implement new readme generator #61

merged 40 commits into from
Jun 18, 2018

Conversation

osterman
Copy link
Member

@osterman osterman commented Jun 14, 2018 •
edited
Loading

what

  • Implement a new README.md generator.
  • Use a README.yaml datasource
  • Support automatic inclusion of files in docs/ (e.g. targets.md like in this repo)
  • Drop support for recursion
  • Add a readme/lint target to ensure README.md is up to date

why

  • Create a very easy format for defining consistent READMEs
  • The README.yaml can be read by our hugo docs site to include specific sections in our documentation

references

design

  • The design was a little bit influenced by hugo and it's use of "frontmatter"
  • the REAMDE.md in this repo was generated from templates/README.md by using the data in README.yaml -- no other magic
  • by default, build-harness will use the templates/README.md gomplate
  • we can have different versions of this template. for now, this isi the only one.
  • Recursion was removed b/c it leads to complicated templates that are difficult for others to understand
  • Support for terraform variable and output documentation can be supported by writing their values to docs/outputs.md and docs/variables.md and then including them in the includes parameter in the README.yaml config

todo

  • add a target to generate terraform variable/output documentation
  • Link to documention hub
  • Related repos section
  • Logo support
  • link to open source project
  • Related repos section
  • Link to jobs
  • Link to “paid support” page

@osterman osterman added enhancement New feature or request wip Work in Progress: Not ready for final review or merge labels Jun 14, 2018
@osterman osterman requested review from goruha and aknysh June 14, 2018 22:20
aknysh
aknysh reviewed Jun 15, 2018
View reviewed changes
templates/README.md Outdated

**Got a question?**

File a GitHub [issue]({{ printf "https://github.com/%s/issues" (ds "config").github_repo}}), send us an [email][email] or join our [Slack Community][slack]).
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

or join our [Slack Community][slack] - delete )

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Too redundant?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Just an unnecessary closing )

image

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

thanks. good catch - i see.

aknysh
aknysh reviewed Jun 15, 2018
View reviewed changes
templates/README.md Outdated

## Community Forum

Get access to our [Open Source Community Forum][slack] on Slack. It's **FREE** to join for everyone! Our "SweetOps" community is where you get to talk with others who share a similar vision for how to rollout and manage infrastructure. This is the best place to talk shop, ask questions, solict feedback, and work together as a community to build *sweet* infrastructure.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

solicit feedback

aknysh
aknysh reviewed Jun 15, 2018
View reviewed changes
templates/README.md Outdated
{{ if eq (ds "config").license "APACHE2" }}
## License

[APACHE 2.0](LICENSE) © 2017 [Cloud Posse, LLC](https://cloudposse.com)
Copy link
Member

@aknysh aknysh Jun 15, 2018 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

can we auto-generate the year here?
maybe a fixed start year and auto-generated current year if it's greater then the start year

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

yea, good idea.

aknysh
aknysh reviewed Jun 15, 2018
View reviewed changes
Copy link
Member

@aknysh aknysh left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

+1
inline comments

@osterman osterman removed the wip Work in Progress: Not ready for final review or merge label Jun 15, 2018
sarkis
sarkis approved these changes Jun 18, 2018
View reviewed changes
README.yaml Outdated
# License of this project
license: "APACHE2"

# Cannonical GitHub repo
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Canonical

@osterman osterman merged commit 2d26d2e into master Jun 18, 2018
@osterman osterman deleted the better-readme branch June 18, 2018 01:57
charlieparkes added a commit to charlieparkes/build-harness that referenced this pull request Jul 29, 2020
@charlieparkes
Shell calls in make are raining on my parade (cloudposse#61)
ddecd23
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@aknysh aknysh aknysh left review comments

@sarkis sarkis sarkis approved these changes

@goruha goruha Awaiting requested review from goruha

Assignees
No one assigned
Labels
enhancement New feature or request
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.
3 participants
@osterman @sarkis @aknysh