mdtoc 0.3.0 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2c01cef42824ceeae479dc235cbe2c7565c2d6ef045074c8d55b34a821ee719d
-  data.tar.gz: c25c67f2bf841dd9e1e3bb6a632035693299e7a53367b5dd255ecfbc125adab2
+  metadata.gz: dd651a744c265508fe1b78eae797f688f83a417d0710ed70fdff838a05e8e2b9
+  data.tar.gz: bfd727b632d7d5076ef17e309e1a2715f5de971a313e74190b9e1facadcade7a
 SHA512:
-  metadata.gz: 603bec1ab105a7438bb2d0c2e4fb0c7eead9c63b57bfe33ca9354b05458d435805ce614cd11549527749092f2cffdc1289691a177b3c86161bac714f877c3eb7
-  data.tar.gz: 6bb0b63c4217f899d2277ba35baf7966cd97219e88f111c7a842b535108c698ac0260c0cc1f2c7e24858c9464a9cac333ea1fa4a7244104b051ba3184ed326bd
+  metadata.gz: 2282ca2fb424b8dc093c856c83d4c13373bc10206d0a0f6c80c05c83329d057d1b3ce2c8dcf1a68ca2a7f303df22b95fccf3a71c1ead0f4c4e6da8049477005e
+  data.tar.gz: 714e58db5f76da82a910398f308698ed049bd56c9632b85d7131465d04d247ac57a0648b718f28b37dfa86be275535b0aee31a0cf5362a4f86523ced23037151

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2020 andornaut
+
+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.

data/README.md

@@ -0,0 +1,112 @@
+# mdtoc - Markdown Table of Contents
+
+Read Markdown files and output a table of contents.
+
+## Installation
+
+Requirements:
+
+* [Ruby](https://www.ruby-lang.org/en/) (see [.ruby-version](./.ruby-version))
+
+```bash
+gem install mdtoc
+```
+
+## Usage
+
+```bash
+$ mdtoc --help
+Usage: mdtoc [options] files or directories...
+    -h, --help                       Show this message
+    -o, --output PATH                Update a table of contents in the file at PATH
+    -a, --[no-]append                Append to the --output file if a <!-- mdtoc --> tag isn't found
+    -c, --[no-]create                Create the --output file if it does not exist
+```
+
+1. Add a `<!-- mdtoc -->` tag to a Markdown file.
+
+  ```bash
+  echo '<!-- mdtoc -->' >> README.md
+  ```
+
+2. Run `mdtoc` and specify input files or directories (eg. the "test/samples" directory) and an output file (eg. "README.md").
+
+  ```bash
+  mdtoc -aco README.md test/samples
+  ```
+
+## Example Rakefile
+
+Create a `Rakefile` with the contents below, then run
+[`rake`](https://github.com/ruby/rake) to:
+
+* `git pullgem push pkg/mdtoc-0.2.0.gem`
+* `git add` any *.md files
+* Run `mdtoc` to update the generated table of contents in the ./README.md file
+* Git commit and push any changes
+
+```ruby
+task default: %w[mdtoc]
+
+desc 'Update Markdown table of contents and push changes to the git repository'
+task :mdtoc do
+  command = <<~CMD
+    set -e
+    if [ -n "$(git diff --name-only --diff-filter=U)" ]; then
+      echo 'Error: conflicts exist' >&2
+      exit 1
+    fi
+    mdtoc --append --create --output README.md docs/
+    git add *.md **/*.md
+    git commit -qm 'Update TOC' || true
+    git pull
+    git push
+  CMD
+  sh command, verbose: false do |ok, status|
+    unless ok
+      fail "Failed with status: #{status.exitstatus}"
+    end
+  end
+end
+```
+
+See [andornaut/til](https://github.com/andornaut/til/blob/master/Rakefile) for an example.
+
+## Development
+
+### Setup
+
+Requirements:
+
+* [Bundler](https://bundler.io/)
+* [chruby](https://github.com/postmodern/chruby) (recommended)
+
+```bash
+# Setup development environment
+bin/setup
+```
+
+### Tasks
+
+```bash
+# List rake tasks
+$ rake -T
+rake build                    # Build gem into the pkg directory
+rake default                  # Run the build, rubocop, sorbet and test tasks
+rake install                  # Build and install gem into system gems
+rake rubocop                  # Run RuboCop
+rake sorbet                   # Run the Sorbet type checker
+rake test                     # Run tests
+```
+# Run mdtoc with test inputs
+$ ruby -Ilib bin/mdtoc test/samples
+
+# Run mdtoc with test inputs, and write to a newly created output file
+$ f=$(mktemp) && ruby -Ilib bin/mdtoc -aco ${f} test/samples ; cat ${f}
+```
+
+### Publishing
+
+```bash
+rake release
+```

data/bin/setup

@@ -0,0 +1,37 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'fileutils'
+
+# path to your application root.
+APP_ROOT = File.expand_path('..', __dir__)
+
+def system!(*args)
+  system(*args) || abort("
+== Command #{args} failed ==")
+end
+
+FileUtils.chdir APP_ROOT do
+  # This script is a way to set up a development environment or update your current one.
+  # You can run it with `bin/setup`.
+
+  puts '== Installing dependencies =='
+  system! 'gem install bundler --conservative'
+  system('bundle check') || system!('bundle install')
+
+  puts "
+== Removing old RBIs =="
+  FileUtils.rm_rf('sorbet/rbi/gems')
+  FileUtils.rm_rf('sorbet/rbi/todo.rbi')
+
+  puts "
+== Generating RBIs =="
+  system! 'bundle exec tapioca gems'
+
+  puts "
+== Initializing Sorbet =="
+  system! 'bundle exec srb tc'
+
+  puts "
+== Setup complete! =="
+end

data/lib/mdtoc/version.rb

@@ -2,5 +2,5 @@
 # frozen_string_literal: true
 
 module Mdtoc
-  VERSION = '0.3.0'
+  VERSION = '0.3.1'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: mdtoc
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.3.1
 platform: ruby
 authors:
 - andornaut
@@ -227,7 +227,10 @@ executables:
 extensions: []
 extra_rdoc_files: []
 files:
+- LICENSE
+- README.md
 - bin/mdtoc
+- bin/setup
 - lib/mdtoc.rb
 - lib/mdtoc/cli.rb
 - lib/mdtoc/markdown/fragment_generator.rb