Make ReadMe

Makes new ReadMe file for GitHub repository

---

Table of Contents

• ⬆️ Top of ReadMe File

• ⚡ Quick Start

  • 📝 Track Repository Customizations
  • 🏭 Utilize Make ReadMe
  • 💾 Commit and Push

• 🗒 Notes

• 📇 Attribution

• ⚖ License

---

Quick Start

Clone the source code of this repository somewhere...

mkdir -vp ~/git/hub/github-utilities
cd ~/git/hub/github-utilities


git clone git@github.com:github-utilities/make-readme.git
cd make-readme

To update in the future pull the master branch of this repository...

cd ~/git/hub/github-utilities/make-readme

git pull origin master

To install updated NPM dependencies from package.json file...

cd ~/git/hub/github-utilities/make-readme

npm install

To force upgrading of NPM dependencies...

npm update

Note, forcing and update of NPM dependencies may cause instabilities and/or merge conflicts; if however everything operates as expected after an update please consider submitting a Pull Request.

Track Repository Customizations

Checkout a branch for tracking Repository customizations...

cd ~/git/hub/github-utilities/make-readme


git checkout -b repository-name

Modify the dataView.json file...

{
  "gfm": true,
  "default_branch": "master",
  "email": "account@host.tld",
  "author": "your-name",
  "organization": "your-name__or__organization-name",
  "repository": "repository-name",
  "output_directory": "~/git/hub/organization-name/repository-name",
  "description": "Quick statement on what this Repository aims to accomplish",
  "is_submodule": false,
  "utilizes_submodules": false,
  "include_notes": false,
  "license": "AGPL-3.0",
  "gh_pages": {
    "branch": "gh-pages",
    "url": false
  },
  "verbose": true,
  "clobber": false,
  "files": [
    {
      "in_path": ".mustache/.github/README.md.mst",
      "out_path": ".github/README.md",
      "partials": [
        ".mustache/partials/readme/quick_start/clone.md.mst",
        ".mustache/partials/readme/quick_start/is_submodule.md.mst",
        ".mustache/partials/readme/quick_start/utilizes_submodules.md.mst",
        ".mustache/partials/readme/notes.md.mst"
      ]
    }
  ]
}

Note, is_submodule and utilizes_submodules are mutually exclusive in regards to either being true, and if both are false then the quick_start_clone.md.mst file is used instead for cloning and updating instructions.

{
  "gfm": true,
  "default_branch": "master",
  "email": "account@host.tld",
  "author": "GitHub-account-name",
  "organization": "organization-name",
  "repository": "repository-name",
  "output_directory": "~/git/hub/organization-name/repository-name",
  "description": "Tests functions of Make ReadMe",
  "license": "AGPL-3.0",
  "is_submodule": false,
  "utilizes_submodules": false,
  "include_notes": true,
  "gh_pages": false,
  "verbose": true,
  "clobber": false,
  "files": [
    {
      "in_path": ".mustache/.github/README.md.mst",
      "out_path": ".github/README.md",
      "partials": [
        ".mustache/partials/readme/quick_start/clone.md.mst",
        ".mustache/partials/readme/quick_start/is_submodule.md.mst",
        ".mustache/partials/readme/quick_start/utilizes_submodules.md.mst",
        ".mustache/partials/readme/notes.md.mst"
      ]
    }
  ]
}

Add and commit changes...

git add -A .

git commit -m 'Customizes defaults from master branch for repository-name'

Utilize Make ReadMe

Initialize a Git repository...

mkdir -vp ~/git/hub/organization-name

git init ~/git/hub/organization-name/repository-name

Note, above should match the same path as defined by output_directory within your customized dataView.json file.

Issue npm run build from this repository...

cd ~/git/hub/github-utilities/make-readme

npm run make-readme

... which will generate files under ~/git/hub/organization-name/repository-name

.github/README.md
LICENSE

Commit and Push

Change directories to the new repository, finish customizing the ReadMe file, and track built files...

cd ~/git/hub/organization-name/repository-name

vim .github/README.md

git add -A .

git commit -m ':tada: Initial commit'

After creating a repository on GitHub, add a remote, and push

git remote add hub git@github.com:organization-name/repository-name.git

git push hub master

🎉 Excellent 🎉 your repository is now finished unitizing the ReadMe file built from this repository!

---

Notes

Pull Requests are most welcomed to add features and/or fix bugs. For example the following four steps show how to add the MIT license to those that are available to add with this project.

0 Checkout the master branch of this repository and write a Mustache template and add a LICENSE file within a named directory...

cd ~/git/hub/github-utilities/make-readme


git checkout master


mkdir -vp .mustache/licenses/MIT

.mustache/licenses/MIT/include.mustache

Copyright {{{ getFullYear }}} {{ author }}

Permission is hereby granted, free of charge, to any person obtaining a copy of
this software and associated documentation files (the "Software"), to deal in
the Software without restriction, including without limitation the rights to
use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
of the Software, and to permit persons to whom the Software is furnished to do
so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

.mustache/licenses/MIT/LICENSE

Copyright <year> <author>

Permission is hereby granted, free of charge, to any person obtaining a copy of
this software and associated documentation files (the "Software"), to deal in
the Software without restriction, including without limitation the rights to
use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
of the Software, and to permit persons to whom the Software is furnished to do
so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

Note, currently this project does not edit/render the selected LICENSE file and instead copies it to the target repository, however the include.mustache file(s) are rendered prior to being included within generated ReadMe file. Pull Requests to add more features in this regard are certainly appreciated.

1 Edit the dataView.json file...

dataView.json

{
  "gfm": true,
  "default_branch": "master",
  "email": "account@host.tld",
  "author": "your-name",
  "organization": "your-name__or__organization-name",
  "repository": "repository-name",
  "output_directory": "~/git/hub/github-utilities/make-readme/tests",
  "description": "Quick statement on what this Repository aims to accomplish",
  "is_submodule": false,
  "utilizes_submodules": false,
  "include_notes": false,
  "license": "MIT",
  "gh_pages": false,
  "verbose": true,
  "clobber": false,
  "files": [
    {
      "in_path": ".mustache/.github/README.md.mst",
      "out_path": ".github/README.md",
      "partials": [
        ".mustache/partials/readme/quick_start/clone.md.mst",
        ".mustache/partials/readme/quick_start/is_submodule.md.mst",
        ".mustache/partials/readme/quick_start/utilizes_submodules.md.mst",
        ".mustache/partials/readme/notes.md.mst"
      ]
    }
  ]
}

... then test...

mkdir -vp tests


npm run build

... and check that generated ReadMe and license files contain the selected license text...

more tests/.github/README.md

more LICENSE

2 Add and commit changes...

git add -A .

git commit -m 'Adds MIT license to generated ReadMe files'

3 After forking on GitHub, add it as a remote and push changes

git remote add fork git@github.com:your-name/make-readme.git

git push fork master

4 Open a Pull Request when your changes are ready.

---

This project utilizes TypeScript to transpile and make stronger assertions of type safety with JavaScript related code, please direct such code edits to the ts/index.ts file then issue npm ts-build to re-build the js/index.js file.

---

Attribution

Resources that where helpful in building this project so far

• GitHub -- janl/mustache.js -- mustache source readPartials

• GitHub -- janl/mustache.js -- mustache documentation API

• StackOverflow -- Windows Batch Files: if else

• StackOverflow -- JavaScript: remove trailing spaces only

• StackOverflow -- How to define function return type of a custom object literal?

• StackOverflow -- Regex to match a string only if a string does not exist

• JSDoc -- Configuring JSDoc

• JSDoc -- Enabling the MarkDown Plugin

• GitHub -- jsdoc2md/jsdoc-to-markdown

• GitHub -- janl/mustache.js#357 -- how to print literal { in front of mustache variable?

---

License

Legal bits of Open Source software

Make ReadMe documentation on how things like this could be utilized
Copyright (C) 2020  S0AndS0

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU Affero General Public License as published
by the Free Software Foundation; version 3 of the License.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU Affero General Public License for more details.

You should have received a copy of the GNU Affero General Public License
along with this program.  If not, see <https://www.gnu.org/licenses/>.