{"action":"closed","number":481,"pull_request":{"url":"https://api.github.com/repos/bhilburn/powerlevel9k/pulls/481","id":115741746,"node_id":"MDExOlB1bGxSZXF1ZXN0MTE1NzQxNzQ2","html_url":"https://github.com/bhilburn/powerlevel9k/pull/481","diff_url":"https://github.com/bhilburn/powerlevel9k/pull/481.diff","patch_url":"https://github.com/bhilburn/powerlevel9k/pull/481.patch","issue_url":"https://api.github.com/repos/bhilburn/powerlevel9k/issues/481","number":481,"state":"closed","locked":false,"title":"Document generation from comments using sh2md (Against NEXT)","user":{"login":"onaforeignshore","id":704406,"node_id":"MDQ6VXNlcjcwNDQwNg==","avatar_url":"https://avatars3.githubusercontent.com/u/704406?v=4","gravatar_id":"","url":"https://api.github.com/users/onaforeignshore","html_url":"https://github.com/onaforeignshore","followers_url":"https://api.github.com/users/onaforeignshore/followers","following_url":"https://api.github.com/users/onaforeignshore/following{/other_user}","gists_url":"https://api.github.com/users/onaforeignshore/gists{/gist_id}","starred_url":"https://api.github.com/users/onaforeignshore/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/onaforeignshore/subscriptions","organizations_url":"https://api.github.com/users/onaforeignshore/orgs","repos_url":"https://api.github.com/users/onaforeignshore/repos","events_url":"https://api.github.com/users/onaforeignshore/events{/privacy}","received_events_url":"https://api.github.com/users/onaforeignshore/received_events","type":"User","site_admin":false},"body":"# Project Documentation / File Commenting\r\n\r\n## Synopsis\r\n\r\nI was thinking about the documenting part of this project, and thought it might be useful to have a reference of all the functions and their calls on the project wiki for our and others' reference.\r\n\r\nI searched online for any converters that would convert bash comments into GitHub markdown, and only found one - [shdoc](https://github.com/reconquest/shdoc). In my opinion, it is lacking a lot, even with the PR that is on the project. So, I have spent the last 3 days rewriting it from scratch.\r\n\r\nI have named my version [sh2md](https://github.com/onaforeignshore/sh2md). Can you guys please take a look at it, and give me comments, as I think it would be useful to start commenting the files and functions in this way. As I have written the converter myself, it will be easy to add / change as required for the project.\r\n\r\nI have included two files in this PR that have been commented in this way - `powerlevel9k.zsh-theme` and `functions/colors.zsh`. I have attached the output to the bottom of this post for you to preview as well.\r\n\r\n## Requirements\r\n\r\nThe converter uses Gnu AWK. As this is available on most systems (and can be installed on Mac using Homebrew), I think it would be available to the majority of the contributors to use to create documentation for their files.\r\n\r\n## TODO\r\n- [ ] discuss the requirements for `powerlevel9k`\r\n- [ ] discuss the styles and tags we would like to use\r\n- [x] add a function to convert multiple line comments into paragraphs\r\n- [ ] add more section tags as required\r\n\r\n## Examples\r\n\r\n### File level comment block\r\n\r\n```sh\r\n################################################################\r\n# @title powerlevel9k Theme\r\n# @source https://github.com/bhilburn/powerlevel9k\r\n#\r\n# @authors\r\n#   Ben Hilburn\r\n#   Dominic Ritter\r\n#\r\n# @info\r\n# This theme was inspired by [agnoster's Theme](https://gist.github.com/3712874)\r\n#\r\n# For basic documentation, please refer to the README.md in the top-level\r\n# directory. For more detailed documentation, refer to the\r\n# [project wiki](https://github.com/bhilburn/powerlevel9k/wiki), hosted\r\n# on Github.\r\n#\r\n# There are a lot of easy ways you can customize your prompt segments and\r\n# theming with simple variables defined in your `~/.zshrc`.\r\n################################################################\r\n```\r\n\r\n---\r\n\r\n# powerlevel9k Theme\r\n\r\n### Source(s)\r\n\r\n[https://github.com/bhilburn/powerlevel9k](#https://github.com/bhilburn/powerlevel9k)\r\n\r\n### Author(s)\r\n\r\n- Ben Hilburn\r\n- Dominic Ritter\r\n\r\n### File Description\r\n\r\n\r\n_This theme was inspired by [agnoster's Theme](https://gist.github.com/3712874)_\r\n\r\n_For basic documentation, please refer to the README.md in the top-level directory. For more detailed documentation, refer to the [project wiki](https://github.com/bhilburn/powerlevel9k/wiki), hosted on Github._\r\n\r\n_There are a lot of easy ways you can customize your prompt segments and theming with simple variables defined in your `~/.zshrc`._\r\n\r\n---\r\n\r\n### Function comment blocks\r\n\r\n```sh\r\n#!/usr/bin/env zsh\r\n# vim:ft=zsh ts=2 sw=2 sts=2 et fenc=utf-8\r\n################################################################\r\n# @title Color functions\r\n# @source https://github.com/bhilburn/powerlevel9k\r\n# @info\r\n# This file holds some color-functions for the powerlevel9k-ZSH-theme\r\n##\r\n\r\n################################################################\r\n# @description\r\n# Get numerical color codes. That way we translate ANSI codes ZSH-Style color codes.\r\n#\r\n# @example\r\n#   getColorCode 'black'\r\n#\r\n# @args\r\n#   $1 string|number If string, ANSI color code.\r\n#\r\n# @returns\r\n#   Zsh style color code.\r\n##\r\nfunction getColorCode() {\r\n  # ...\r\n}\r\n\r\n################################################################\r\n# @description\r\n# Check if two colors are equal, even if one is specified as ANSI code.\r\n#\r\n# @examples isSameColor 'black' 0\r\n#   isSameColor 'white' 0\r\n#\r\n# @args\r\n#   $1 string|number First color.\r\n#   $2 string|number Second color.\r\n#\r\n# @returns\r\n#   true if they are the same color.\r\n#   false if they are different colors.\r\n#\r\n# @see\r\n#   getColorCode\r\n##\r\nfunction isSameColor() {\r\n  # ...\r\n}\r\n```\r\n\r\n---\r\n\r\n# Color functions\r\n\r\n### Source(s)\r\n\r\n[https://github.com/bhilburn/powerlevel9k](#https://github.com/bhilburn/powerlevel9k)\r\n\r\n### File Description\r\n\r\n\r\n_This file holds some color-functions for the powerlevel9k-ZSH-theme_\r\n\r\n\r\n## Table of Contents\r\n\r\n- [getColorCode()](#getColorCode)\r\n- [isSameColor()](#isSameColor)\r\n\r\n## getColorCode()\r\n\r\nGet numerical color codes. That way we translate ANSI codes ZSH-Style color codes.\r\n\r\n### Example\r\n\r\n```sh\r\ngetColorCode 'black'\r\n```\r\n\r\n### Arguments\r\n\r\n- **$1** (string|number) If string, ANSI color code.\r\n\r\n### Returns\r\n\r\n- Zsh style color code.\r\n\r\n## isSameColor()\r\n\r\nCheck if two colors are equal, even if one is specified as ANSI code.\r\n\r\n### Example\r\n\r\n```sh\r\nisSameColor 'black' 0\r\nisSameColor 'white' 0\r\n```\r\n\r\n### Arguments\r\n\r\n- **$1** (string|number) First color.\r\n- **$2** (string|number) Second color.\r\n\r\n### Returns\r\n\r\n- true if they are the same color.\r\n- false if they are different colors.\r\n\r\n### See also\r\n\r\n- [getColorCode](#getColorCode)\r\n\r\n---\r\n","created_at":"2017-04-13T12:01:30Z","updated_at":"2018-09-15T11:37:35Z","closed_at":"2018-09-15T11:37:35Z","merged_at":null,"merge_commit_sha":"4ae86194d6bcd26b4c340ba261cecf2da8d1af3f","assignee":null,"assignees":[],"requested_reviewers":[],"requested_teams":[],"labels":[],"milestone":null,"commits_url":"https://api.github.com/repos/bhilburn/powerlevel9k/pulls/481/commits","review_comments_url":"https://api.github.com/repos/bhilburn/powerlevel9k/pulls/481/comments","review_comment_url":"https://api.github.com/repos/bhilburn/powerlevel9k/pulls/comments{/number}","comments_url":"https://api.github.com/repos/bhilburn/powerlevel9k/issues/481/comments","statuses_url":"https://api.github.com/repos/bhilburn/powerlevel9k/statuses/2d85b0fba850431d1e423b1d8a97b036b58734b9","head":{"label":"onaforeignshore:docs","ref":"docs","sha":"2d85b0fba850431d1e423b1d8a97b036b58734b9","user":{"login":"onaforeignshore","id":704406,"node_id":"MDQ6VXNlcjcwNDQwNg==","avatar_url":"https://avatars3.githubusercontent.com/u/704406?v=4","gravatar_id":"","url":"https://api.github.com/users/onaforeignshore","html_url":"https://github.com/onaforeignshore","followers_url":"https://api.github.com/users/onaforeignshore/followers","following_url":"https://api.github.com/users/onaforeignshore/following{/other_user}","gists_url":"https://api.github.com/users/onaforeignshore/gists{/gist_id}","starred_url":"https://api.github.com/users/onaforeignshore/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/onaforeignshore/subscriptions","organizations_url":"https://api.github.com/users/onaforeignshore/orgs","repos_url":"https://api.github.com/users/onaforeignshore/repos","events_url":"https://api.github.com/users/onaforeignshore/events{/privacy}","received_events_url":"https://api.github.com/users/onaforeignshore/received_events","type":"User","site_admin":false},"repo":{"id":87598054,"node_id":"MDEwOlJlcG9zaXRvcnk4NzU5ODA1NA==","name":"powerlevel9k","full_name":"onaforeignshore/powerlevel9k","owner":{"login":"onaforeignshore","id":704406,"node_id":"MDQ6VXNlcjcwNDQwNg==","avatar_url":"https://avatars3.githubusercontent.com/u/704406?v=4","gravatar_id":"","url":"https://api.github.com/users/onaforeignshore","html_url":"https://github.com/onaforeignshore","followers_url":"https://api.github.com/users/onaforeignshore/followers","following_url":"https://api.github.com/users/onaforeignshore/following{/other_user}","gists_url":"https://api.github.com/users/onaforeignshore/gists{/gist_id}","starred_url":"https://api.github.com/users/onaforeignshore/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/onaforeignshore/subscriptions","organizations_url":"https://api.github.com/users/onaforeignshore/orgs","repos_url":"https://api.github.com/users/onaforeignshore/repos","events_url":"https://api.github.com/users/onaforeignshore/events{/privacy}","received_events_url":"https://api.github.com/users/onaforeignshore/received_events","type":"User","site_admin":false},"private":false,"html_url":"https://github.com/onaforeignshore/powerlevel9k","description":"The most awesome Powerline theme for ZSH around!","fork":true,"url":"https://api.github.com/repos/onaforeignshore/powerlevel9k","forks_url":"https://api.github.com/repos/onaforeignshore/powerlevel9k/forks","keys_url":"https://api.github.com/repos/onaforeignshore/powerlevel9k/keys{/key_id}","collaborators_url":"https://api.github.com/repos/onaforeignshore/powerlevel9k/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/onaforeignshore/powerlevel9k/teams","hooks_url":"https://api.github.com/repos/onaforeignshore/powerlevel9k/hooks","issue_events_url":"https://api.github.com/repos/onaforeignshore/powerlevel9k/issues/events{/number}","events_url":"https://api.github.com/repos/onaforeignshore/powerlevel9k/events","assignees_url":"https://api.github.com/repos/onaforeignshore/powerlevel9k/assignees{/user}","branches_url":"https://api.github.com/repos/onaforeignshore/powerlevel9k/branches{/branch}","tags_url":"https://api.github.com/repos/onaforeignshore/powerlevel9k/tags","blobs_url":"https://api.github.com/repos/onaforeignshore/powerlevel9k/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/onaforeignshore/powerlevel9k/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/onaforeignshore/powerlevel9k/git/refs{/sha}","trees_url":"https://api.github.com/repos/onaforeignshore/powerlevel9k/git/trees{/sha}","statuses_url":"https://api.github.com/repos/onaforeignshore/powerlevel9k/statuses/{sha}","languages_url":"https://api.github.com/repos/onaforeignshore/powerlevel9k/languages","stargazers_url":"https://api.github.com/repos/onaforeignshore/powerlevel9k/stargazers","contributors_url":"https://api.github.com/repos/onaforeignshore/powerlevel9k/contributors","subscribers_url":"https://api.github.com/repos/onaforeignshore/powerlevel9k/subscribers","subscription_url":"https://api.github.com/repos/onaforeignshore/powerlevel9k/subscription","commits_url":"https://api.github.com/repos/onaforeignshore/powerlevel9k/commits{/sha}","git_commits_url":"https://api.github.com/repos/onaforeignshore/powerlevel9k/git/commits{/sha}","comments_url":"https://api.github.com/repos/onaforeignshore/powerlevel9k/comments{/number}","issue_comment_url":"https://api.github.com/repos/onaforeignshore/powerlevel9k/issues/comments{/number}","contents_url":"https://api.github.com/repos/onaforeignshore/powerlevel9k/contents/{+path}","compare_url":"https://api.github.com/repos/onaforeignshore/powerlevel9k/compare/{base}...{head}","merges_url":"https://api.github.com/repos/onaforeignshore/powerlevel9k/merges","archive_url":"https://api.github.com/repos/onaforeignshore/powerlevel9k/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/onaforeignshore/powerlevel9k/downloads","issues_url":"https://api.github.com/repos/onaforeignshore/powerlevel9k/issues{/number}","pulls_url":"https://api.github.com/repos/onaforeignshore/powerlevel9k/pulls{/number}","milestones_url":"https://api.github.com/repos/onaforeignshore/powerlevel9k/milestones{/number}","notifications_url":"https://api.github.com/repos/onaforeignshore/powerlevel9k/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/onaforeignshore/powerlevel9k/labels{/name}","releases_url":"https://api.github.com/repos/onaforeignshore/powerlevel9k/releases{/id}","deployments_url":"https://api.github.com/repos/onaforeignshore/powerlevel9k/deployments","created_at":"2017-04-08T01:01:07Z","updated_at":"2018-09-06T14:13:17Z","pushed_at":"2018-09-15T11:37:34Z","git_url":"git://github.com/onaforeignshore/powerlevel9k.git","ssh_url":"git@github.com:onaforeignshore/powerlevel9k.git","clone_url":"https://github.com/onaforeignshore/powerlevel9k.git","svn_url":"https://github.com/onaforeignshore/powerlevel9k","homepage":"","size":2767,"stargazers_count":0,"watchers_count":0,"language":"Shell","has_issues":false,"has_projects":true,"has_downloads":true,"has_wiki":true,"has_pages":false,"forks_count":0,"mirror_url":null,"archived":false,"open_issues_count":1,"license":{"key":"mit","name":"MIT License","spdx_id":"MIT","url":"https://api.github.com/licenses/mit","node_id":"MDc6TGljZW5zZTEz"},"forks":0,"open_issues":1,"watchers":0,"default_branch":"master"}},"base":{"label":"bhilburn:next","ref":"next","sha":"2be5d5071eaec4b6baecd45bca9ecb085953b763","user":{"login":"bhilburn","id":569571,"node_id":"MDQ6VXNlcjU2OTU3MQ==","avatar_url":"https://avatars1.githubusercontent.com/u/569571?v=4","gravatar_id":"","url":"https://api.github.com/users/bhilburn","html_url":"https://github.com/bhilburn","followers_url":"https://api.github.com/users/bhilburn/followers","following_url":"https://api.github.com/users/bhilburn/following{/other_user}","gists_url":"https://api.github.com/users/bhilburn/gists{/gist_id}","starred_url":"https://api.github.com/users/bhilburn/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/bhilburn/subscriptions","organizations_url":"https://api.github.com/users/bhilburn/orgs","repos_url":"https://api.github.com/users/bhilburn/repos","events_url":"https://api.github.com/users/bhilburn/events{/privacy}","received_events_url":"https://api.github.com/users/bhilburn/received_events","type":"User","site_admin":false},"repo":{"id":30003816,"node_id":"MDEwOlJlcG9zaXRvcnkzMDAwMzgxNg==","name":"powerlevel9k","full_name":"bhilburn/powerlevel9k","owner":{"login":"bhilburn","id":569571,"node_id":"MDQ6VXNlcjU2OTU3MQ==","avatar_url":"https://avatars1.githubusercontent.com/u/569571?v=4","gravatar_id":"","url":"https://api.github.com/users/bhilburn","html_url":"https://github.com/bhilburn","followers_url":"https://api.github.com/users/bhilburn/followers","following_url":"https://api.github.com/users/bhilburn/following{/other_user}","gists_url":"https://api.github.com/users/bhilburn/gists{/gist_id}","starred_url":"https://api.github.com/users/bhilburn/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/bhilburn/subscriptions","organizations_url":"https://api.github.com/users/bhilburn/orgs","repos_url":"https://api.github.com/users/bhilburn/repos","events_url":"https://api.github.com/users/bhilburn/events{/privacy}","received_events_url":"https://api.github.com/users/bhilburn/received_events","type":"User","site_admin":false},"private":false,"html_url":"https://github.com/bhilburn/powerlevel9k","description":"The most awesome Powerline theme for ZSH around!","fork":false,"url":"https://api.github.com/repos/bhilburn/powerlevel9k","forks_url":"https://api.github.com/repos/bhilburn/powerlevel9k/forks","keys_url":"https://api.github.com/repos/bhilburn/powerlevel9k/keys{/key_id}","collaborators_url":"https://api.github.com/repos/bhilburn/powerlevel9k/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/bhilburn/powerlevel9k/teams","hooks_url":"https://api.github.com/repos/bhilburn/powerlevel9k/hooks","issue_events_url":"https://api.github.com/repos/bhilburn/powerlevel9k/issues/events{/number}","events_url":"https://api.github.com/repos/bhilburn/powerlevel9k/events","assignees_url":"https://api.github.com/repos/bhilburn/powerlevel9k/assignees{/user}","branches_url":"https://api.github.com/repos/bhilburn/powerlevel9k/branches{/branch}","tags_url":"https://api.github.com/repos/bhilburn/powerlevel9k/tags","blobs_url":"https://api.github.com/repos/bhilburn/powerlevel9k/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/bhilburn/powerlevel9k/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/bhilburn/powerlevel9k/git/refs{/sha}","trees_url":"https://api.github.com/repos/bhilburn/powerlevel9k/git/trees{/sha}","statuses_url":"https://api.github.com/repos/bhilburn/powerlevel9k/statuses/{sha}","languages_url":"https://api.github.com/repos/bhilburn/powerlevel9k/languages","stargazers_url":"https://api.github.com/repos/bhilburn/powerlevel9k/stargazers","contributors_url":"https://api.github.com/repos/bhilburn/powerlevel9k/contributors","subscribers_url":"https://api.github.com/repos/bhilburn/powerlevel9k/subscribers","subscription_url":"https://api.github.com/repos/bhilburn/powerlevel9k/subscription","commits_url":"https://api.github.com/repos/bhilburn/powerlevel9k/commits{/sha}","git_commits_url":"https://api.github.com/repos/bhilburn/powerlevel9k/git/commits{/sha}","comments_url":"https://api.github.com/repos/bhilburn/powerlevel9k/comments{/number}","issue_comment_url":"https://api.github.com/repos/bhilburn/powerlevel9k/issues/comments{/number}","contents_url":"https://api.github.com/repos/bhilburn/powerlevel9k/contents/{+path}","compare_url":"https://api.github.com/repos/bhilburn/powerlevel9k/compare/{base}...{head}","merges_url":"https://api.github.com/repos/bhilburn/powerlevel9k/merges","archive_url":"https://api.github.com/repos/bhilburn/powerlevel9k/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/bhilburn/powerlevel9k/downloads","issues_url":"https://api.github.com/repos/bhilburn/powerlevel9k/issues{/number}","pulls_url":"https://api.github.com/repos/bhilburn/powerlevel9k/pulls{/number}","milestones_url":"https://api.github.com/repos/bhilburn/powerlevel9k/milestones{/number}","notifications_url":"https://api.github.com/repos/bhilburn/powerlevel9k/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/bhilburn/powerlevel9k/labels{/name}","releases_url":"https://api.github.com/repos/bhilburn/powerlevel9k/releases{/id}","deployments_url":"https://api.github.com/repos/bhilburn/powerlevel9k/deployments","created_at":"2015-01-29T04:36:00Z","updated_at":"2018-09-15T06:50:29Z","pushed_at":"2018-09-15T09:28:50Z","git_url":"git://github.com/bhilburn/powerlevel9k.git","ssh_url":"git@github.com:bhilburn/powerlevel9k.git","clone_url":"https://github.com/bhilburn/powerlevel9k.git","svn_url":"https://github.com/bhilburn/powerlevel9k","homepage":"","size":2004,"stargazers_count":6254,"watchers_count":6254,"language":"Shell","has_issues":true,"has_projects":true,"has_downloads":true,"has_wiki":true,"has_pages":false,"forks_count":523,"mirror_url":null,"archived":false,"open_issues_count":123,"license":{"key":"mit","name":"MIT License","spdx_id":"MIT","url":"https://api.github.com/licenses/mit","node_id":"MDc6TGljZW5zZTEz"},"forks":523,"open_issues":123,"watchers":6254,"default_branch":"master"}},"_links":{"self":{"href":"https://api.github.com/repos/bhilburn/powerlevel9k/pulls/481"},"html":{"href":"https://github.com/bhilburn/powerlevel9k/pull/481"},"issue":{"href":"https://api.github.com/repos/bhilburn/powerlevel9k/issues/481"},"comments":{"href":"https://api.github.com/repos/bhilburn/powerlevel9k/issues/481/comments"},"review_comments":{"href":"https://api.github.com/repos/bhilburn/powerlevel9k/pulls/481/comments"},"review_comment":{"href":"https://api.github.com/repos/bhilburn/powerlevel9k/pulls/comments{/number}"},"commits":{"href":"https://api.github.com/repos/bhilburn/powerlevel9k/pulls/481/commits"},"statuses":{"href":"https://api.github.com/repos/bhilburn/powerlevel9k/statuses/2d85b0fba850431d1e423b1d8a97b036b58734b9"}},"author_association":"CONTRIBUTOR","merged":false,"mergeable":null,"rebaseable":null,"mergeable_state":"unknown","merged_by":null,"comments":3,"review_comments":0,"maintainer_can_modify":false,"commits":4,"additions":54,"deletions":16,"changed_files":6}}
{"actor":{"display_login":"onaforeignshore"}}