https://github.com/esotericpig/yard_ghurt
:fallen_leaf::sunrise_over_mountains::icecream: YARDoc GitHub Rake Tasks.
https://github.com/esotericpig/yard_ghurt
gfm github-flavored-markdown github-pages rake rake-task ruby yardoc
Last synced: 4 months ago
JSON representation
:fallen_leaf::sunrise_over_mountains::icecream: YARDoc GitHub Rake Tasks.
- Host: GitHub
- URL: https://github.com/esotericpig/yard_ghurt
- Owner: esotericpig
- License: lgpl-3.0
- Created: 2019-07-15T12:57:41.000Z (over 6 years ago)
- Default Branch: master
- Last Pushed: 2021-06-20T10:53:35.000Z (over 4 years ago)
- Last Synced: 2024-03-15T01:03:44.985Z (almost 2 years ago)
- Topics: gfm, github-flavored-markdown, github-pages, rake, rake-task, ruby, yardoc
- Language: Ruby
- Homepage:
- Size: 65.4 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE.txt
Awesome Lists containing this project
README
# YardGhurt
[](https://badge.fury.io/rb/yard_ghurt)
[](https://esotericpig.github.io/docs/yard_ghurt/yardoc/index.html)
[](https://github.com/esotericpig/yard_ghurt)
[](CHANGELOG.md)
[](LICENSE.txt)
YARDoc GitHub Rake Tasks
- Fix GitHub Flavored Markdown files.
- Sync YARDoc to a local GitHub Pages repo.
## Contents
- [Setup](#setup)
- [Using](#using)
- [GFMFixTask](#gfmfixtask)
- [GHPSyncTask](#ghpsynctask)
- [Util / YardGhurt](#util--yardghurt)
- [AnchorLinks](#anchorlinks)
- [CLI App](#cli-app)
- [Hacking](#hacking)
- [Testing](#testing)
- [Tests](#tests)
- [License](#license)
## [Setup](#contents)
Pick your poison...
With the RubyGems CLI package manager:
`$ gem install yard_ghurt`
In your *Gemspec* (*<project>.gemspec*):
```Ruby
spec.add_development_dependency 'yard_ghurt', '~> X.X.X'
```
In your *Gemfile*:
```Ruby
gem 'yard_ghurt', '~> X.X.X', :group => [:development, :test]
# or...
gem 'yard_ghurt', :git => 'https://github.com/esotericpig/yard_ghurt.git',
:tag => 'vX.X.X', :group => [:development, :test]
```
Manually:
```
$ git clone 'https://github.com/esotericpig/yard_ghurt.git'
$ cd yard_ghurt
$ bundle install
$ bundle exec rake install:local
```
## [Using](#contents)
Currently, you can't use this project as a YARDoc Plugin, but planning on it for v2.0. Read the [TODO](TODO.md) for more info.
**Rake Tasks:**
| Task | Description |
| --- | --- |
| [GFMFixTask](#gfmfixtask) | Fix GitHub Flavored Markdown files |
| [GHPSyncTask](#ghpsynctask) | Sync YARDoc to a local GitHub Pages repo. |
**Helpers:**
| Helper | Description |
| --- | --- |
| [Util / YardGhurt](#util--yardghurt) | Utility methods for tasks |
| [AnchorLinks](#anchorlinks) | A “database” of anchor links |
### [GFMFixTask](#using)
Fix (find & replace) text in the GitHub Flavored Markdown (GFM) files in the YARDoc directory, for differences between the two formats.
**Very Important!**
In order for this to work, you must also add `redcarpet` as a dependency, per YARDoc's documentation:
```Ruby
spec.add_development_dependency 'redcarpet','~> X.X' # For YARDoc Markdown (*.md)
```
Else, you'll get a bunch of `label-*` relative links.
You can set *dry_run* on the command line:
`$ rake yard_gfm_fix dryrun=true`
**What I typically use:**
```Ruby
YardGhurt::GFMFixTask.new() do |task|
task.arg_names = [:dev]
task.dry_run = false
task.fix_code_langs = true
task.md_files = ['index.html']
task.before = Proc.new() do |t2,args|
# Delete this file as it's never used (index.html is an exact copy)
YardGhurt.rm_exist(File.join(t2.doc_dir,'file.README.html'))
# Root dir of my GitHub Page for CSS/JS
ghp_root_dir = YardGhurt.to_bool(args.dev) ? '../../esotericpig.github.io' : '../../..'
t2.css_styles << %Q()
t2.js_scripts << %Q()
end
end
```
**Using all options:**
```Ruby
YardGhurt::GFMFixTask.new(:yard_fix) do |task|
task.anchor_db = {'tests' => 'Testing'} # #tests => #Testing
task.arg_names << :name # Custom args
task.css_styles << '' # Inserted at
task.css_styles << 'body{ background-color: linen; }'
task.custom_gsub = Proc.new() {|line| !line.gsub!('YardGhurt','YARD GHURT!').nil?()}
task.custom_gsubs << [/newline/i,'Do you smell what The Rock is cooking?']
task.deps << :yard # Custom dependencies
task.description = 'Fix it'
task.doc_dir = 'doc'
task.dry_run = false
task.exclude_code_langs = Set['ruby']
task.fix_anchor_links = true
task.fix_code_langs = true
task.fix_file_links = true
task.js_scripts << '' # Inserted at