boondoc 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: f854aff827f84fc734634d7e01d80908ff4f347532ab20cce7996771876b9f1f
+  data.tar.gz: 3ebdb2551d145c72e70639cad96e5f31366fbe98e21db115da1a8964f9b8d2a2
+SHA512:
+  metadata.gz: e7cdde7b2696fa3bca5cf2b8dcb7825ea28ffe4c2f69db5fa41444330fa7d6910b5ec683f11ab21106cca39c2978fe247dcd2b701d4d27f15753bbb6fb912427
+  data.tar.gz: d78c6cca549633e526d9f979d59d0bc653fb4339c23f57a51370ef8b57c14e296c77ab3f8f803c58818e356bc188b07d5f80294449a1179a178b401e7a064878

data/CHANGELOG.md

@@ -0,0 +1,17 @@
+## [Unreleased]
+
+## [0.1.0] - 2026-10-25
+
+### ✨ Features
+- **Markdown docs from YARD comments:** Prism-based parsing of YARD-style comments, with one markdown page per class or module.
+- **Stitched README and extra files**, with reference links between pages.
+- **YARD bridge (optional):** `--yard-macros` hands YARD only the files that contain macros or directives, and warns when a project has none.
+- **Assets:** the `assets` option (`--assets`, or `--asset` in `.yardopts`) copies files such as images into the output, and `copy_linked_assets` also copies the files that pages embed. Links to a copied file, in the README, stitched files, and doc comments, point at the copy. A file that is no longer copied is removed like a stale page.
+- **`.yardopts` support:** reads the source globs, the extra files after `-` and `--files`, `--readme`, `--title`, `--private`, `--protected`, and `--exclude`. `.boondoc.yml` and the command line win over it, key by key, and `--no-yardopts` (or `yardopts: false`) skips it. `--output-dir` is never used, and other options are listed as ignored.
+- **`boondoc serve`** warns when `--host` is not a loopback address. Links to source files 404 under `serve`, because they point outside the output directory.
+- **Case-safe file names:** classes and modules such as `Guard::CLI` and `Guard::Cli` now get their kind in the file name (`CLI.class.md`, `Cli.module.md`) instead of overwriting each other on case-insensitive filesystems.
+
+### 🔒 Security
+- `{include:file:...}`, `readme`, and `files` only read files inside the project, and Boondoc never writes or deletes through a symlink inside the output directory, or outside it.
+- The output directory must be inside the project and may not be, or sit below, a symlink. `--allow-outside-output` (command line and Rake options only, never `.boondoc.yml`) allows an output directory outside the project; that directory is not checked for symlinks.
+- Ruby files that resolve outside the project (an absolute glob, `../`, or a symlink) are skipped with a warning, so `--strict` fails.

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,10 @@
+# Code of Conduct
+
+"Boondoc" follows [The Ruby Community Conduct Guideline](https://www.ruby-lang.org/en/conduct) in all "collaborative space", which is defined as community communications channels (such as mailing lists, submitted patches, commit comments, etc.):
+
+* Participants will be tolerant of opposing views.
+* Participants must ensure that their language and actions are free of personal attacks and disparaging personal remarks.
+* When interpreting the words and actions of others, participants should always assume good intentions.
+* Behaviour which can be reasonably considered harassment will not be tolerated.
+
+If you have any concerns about behaviour within this project, please contact us at ["joesharp13@gmail.com"](mailto:"joesharp13@gmail.com").

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Joe Sharp
+
+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,345 @@
+# Boondoc
+
+Markdown-only API documentation for Ruby.
+
+Boondoc reads the YARD-style comments you already write and produces plain
+GitHub-flavored markdown: one file per class or module, an index, and working
+relative links between them. There is no HTML and no site to deploy or host. The
+output renders directly in a repository's `docs/` folder.
+
+Because everything is markdown from start to finish, your README, changelog
+and guides are stitched in as they are, and `{Foo#bar}` references inside them
+become real links.
+
+## Installation
+
+```sh
+bundle add boondoc --group development
+```
+
+or
+
+```sh
+gem install boondoc
+```
+
+Boondoc needs Ruby 3.3 or newer.
+
+## Usage
+
+```sh
+boondoc                                  # document lib/**/*.rb into docs/
+boondoc 'app/**/*.rb' lib -o docs/api    # choose the sources and the output
+boondoc --files CHANGELOG.md 'guides/*.md'
+```
+
+| Option | Meaning |
+| --- | --- |
+| `-o`, `--output DIR` | Output directory. Default `docs`. It must be inside the project, see `--allow-outside-output`. |
+| `--index NAME` | Name of the index page. Default `README.md`, which GitHub shows when browsing the folder. |
+| `--readme FILE` | File used as the top of the index page. Default `README.md` if present. |
+| `--skip-readme` | Leave the README out of the index page. |
+| `--files a.md b/*.md` | Extra files to stitch in. |
+| `--assets FILES` | Files, directories, or globs to copy into the output, such as images. `FROM:DIR` copies into `DIR` instead. See [Assets](#assets). |
+| `--copy-linked-assets` | Also copy the files that pages embed, such as images in the README and in doc comments. |
+| `--exclude GLOBS` | Ruby files to leave out. |
+| `--title TITLE` | Index title when there is no README. |
+| `--private`, `--protected` | Include those methods (and `@private` objects). |
+| `--yard-macros` | Expand `@!macro`, `@!method`, and `@!attribute` with the yard gem. See below. |
+| `--no-yardopts` | Do not read `.yardopts`. See [Reading `.yardopts`](#reading-yardopts). |
+| `--strict` | Exit non-zero on any warning, such as a link that does not resolve. |
+| `--force` | Overwrite files in the output directory that Boondoc did not write. |
+| `--allow-outside-output` | Let the output directory be outside the project, for docs kept outside the repository. This is a security risk if you do not trust the project, see [Where Boondoc reads and writes](#where-boondoc-reads-and-writes). Command line and Rake options only, never `.boondoc.yml`. |
+| `-c`, `--config FILE` | Config file. Default `.boondoc.yml`. |
+| `-q`, `--quiet` | Only print warnings and errors. |
+
+The same settings can live in `.boondoc.yml`:
+
+```yaml
+sources:
+  - lib/**/*.rb
+output: docs
+files:
+  - CHANGELOG.md
+  - guides/*.md
+strict: true
+```
+
+### Rake
+
+```ruby
+require 'boondoc/rake_task'
+
+Boondoc::RakeTask.new(:docs) do |t|
+  t.options = { files: ['CHANGELOG.md'], strict: true }
+end
+```
+
+## What gets written
+
+```
+docs/README.md             your README, then an index of the API and the stitched files
+docs/Foo.md                one page per class or module
+docs/Foo/Bar.md            nested namespaces mirror the directory structure
+docs/top-level.md          top-level methods and constants, if there are any
+docs/files/CHANGELOG.md    stitched files
+docs/.boondoc-manifest     the list of files boondoc wrote
+```
+
+Classes and modules whose names differ only by case, such as `Guard::CLI` and
+`Guard::Cli`, would share a file on case-insensitive filesystems. Boondoc adds
+the kind to both names (`Guard/CLI.class.md` and `Guard/Cli.module.md`, and
+`Guard/Cli.module/` for the children of the module), so the output is the same
+on every platform. Two of the same kind get a number as well (`Cli.class-2.md`).
+Names that don't collide are left alone.
+
+On every run Boondoc removes pages it wrote earlier that no longer correspond
+to anything, and it refuses to overwrite a file it did not write unless you
+pass `--force`. Files you add to the output directory by hand are left alone.
+
+### Where Boondoc reads and writes
+
+Boondoc limits what a project can make it read or write, because the project
+(its comments, symlinks, and `.boondoc.yml`) may come from someone else, such as
+a pull request that CI builds docs for.
+
+- The output directory must be inside the project and must not be, or sit
+  below, a symlink. `.boondoc.yml` cannot move it outside.
+- Ruby files that resolve outside the project, through an absolute path,
+  `../` or a symlink, are skipped with a warning, and `--strict` turns the
+  warning into a failure. A README or extra file outside the project is an
+  error. Run Boondoc from the directory that contains everything you want
+  documented.
+- `{include:file:...}`, `readme`, and `files` only read files inside the project.
+- Boondoc never writes or deletes through a symlink inside the output
+  directory, or outside it.
+
+`--allow-outside-output` (on the command line, or `allow_outside_output: true`
+in Rake options) lifts the first rule, for docs that are kept outside the
+repository. An output directory outside the project is not checked for
+symlinks. It is a security risk if you do not trust the project: its
+`.boondoc.yml` then chooses where files are written and, with `force: true`,
+which files are overwritten. Only pass it for projects you trust, and a
+`.boondoc.yml` that sets it is rejected.
+
+Each method gets an explicit anchor (`<a id="method-i-name"></a>`), because
+GitHub's heading anchors cannot tell `save`, `save?`, and `save!` apart. That
+anchor is the only HTML in the output.
+
+## Viewing the docs
+
+The output is plain markdown with relative links, so anything that renders
+markdown and follows relative links can browse it.
+
+**GitHub.** Commit the output directory and open it on github.com. GitHub
+renders the folder's `README.md` under the file list, which is why the index
+page has that name by default, and the links between pages and to method
+anchors work as they are.
+
+**VS Code.** Open `docs/README.md` and run *Markdown: Open Preview*
+(`Cmd+Shift+V`, or `Ctrl+Shift+V` on Windows and Linux). Links in the preview
+open the other pages, and no extension is needed.
+
+**In a browser, with `boondoc serve`.** This starts a local preview styled
+like github.com:
+
+```sh
+boondoc serve              # serves docs/ at http://127.0.0.1:3333
+boondoc serve -o docs/api --port 4000
+```
+
+It runs the
+[gh-markdown-preview](https://github.com/yusukebe/gh-markdown-preview)
+extension of the [GitHub CLI](https://cli.github.com), so `gh` has to be
+installed. If the extension is missing, Boondoc asks before installing it.
+`serve` reads the output directory from `-o` or `.boondoc.yml`, and it does
+not generate anything: run `boondoc` first.
+
+Links to source files (`../../lib/...`) point outside the output directory, so
+they 404 under `serve`. They work on GitHub and in VS Code.
+
+Serve only docs you trust, and keep the default host. The extension returns any
+file the current user can read through its `/__/md?path=` address, sends the
+markdown it renders to GitHub's markdown API, and does not check the `Host`
+header. Boondoc warns when `--host` is not a loopback address.
+
+To run the extension yourself, start it from inside the output directory:
+
+```sh
+gh extension install yusukebe/gh-markdown-preview
+cd docs && gh markdown-preview --host 127.0.0.1
+```
+
+It always serves files relative to the directory it was started in, so
+`gh markdown-preview docs` from the project root shows the index page but
+every link on it leads to a missing page.
+
+Other previewers work if they resolve links relative to the file being viewed.
+Some editor plugins render only a single file and do not follow links at all.
+
+## Stitching and links
+
+Anywhere in a docstring, a stitched file, or your README:
+
+| Write | Get |
+| --- | --- |
+| `{Foo::Bar}` | a link to that class |
+| `{Foo#bar}`, `{Foo.bar}`, `{#bar}` | a link to that method |
+| `{Foo#bar the bar method}` | the same link with your own text |
+| `{file:CHANGELOG.md}` | a link to a stitched file |
+| `{https://example.com Example}` | an ordinary link |
+| `{include:file:snippets/setup.md}` | the contents of that file, inline |
+| `{include:Foo}` | the docstring of `Foo`, inline |
+| `\{Foo}` | a literal `{Foo}` |
+
+References are resolved the way Ruby resolves constants, from the namespace
+they are written in outwards, and methods are also found on superclasses and
+mixins. Fenced code, indented code, and inline code are never touched, and
+braces that do not look like a reference (`{key: value}`) pass through.
+
+Relative links and images in stitched files are rewritten so they still point
+at the same thing from their new location.
+
+### Assets
+
+Images and other files that pages need are copied into the output, next to the
+pages, so the docs still work when the output directory is published on its
+own. There are two ways to choose them:
+
+- `assets` (or `--assets`, or `--asset` in `.yardopts`) names files, directories,
+  or globs. A directory is copied with everything under it. `images:media` copies
+  into `media/` in the output instead of keeping the project path. Hidden files,
+  symlinks that leave the project, and the output directory itself are skipped.
+- `copy_linked_assets: true` (or `--copy-linked-assets`) also copies the files
+  that pages *embed*: images, `<img>`, `<source srcset>`, `<video poster>`, and
+  `![alt][label]` references. A plain link such as `[the source](lib/foo.rb)`
+  still points back into the project, so it is never copied.
+
+Copied files keep their project path, or the `:DIR` you gave them. Links to them
+are rewritten to point at the copy, in the README, other stitched files, and doc
+comments, which Boondoc rewrites per page so an image in `Foo::Bar` still resolves
+from `docs/Foo/Bar.md`. Files are copied byte for byte, and a copy that is already
+up to date is not touched.
+
+## Supported tags
+
+`@param`, `@option`, `@return`, `@raise`, `@yield`, `@yieldparam`, `@yieldreturn`,
+`@example`, `@overload`, `@see`, `@note`, `@todo`, `@deprecated`, `@abstract`,
+`@since`, `@version`, `@author`, `@api`, `@private`, plus `(see Foo#bar)`
+references. Any other tag is rendered as a labelled line rather than dropped.
+
+Docstrings are treated as markdown and passed through unchanged. RDoc markup
+is not converted.
+
+## Compared with YARD and RDoc
+
+Boondoc reads the same comments YARD does and aims at one thing YARD and RDoc
+do not do: documentation that is markdown all the way through.
+
+| | Boondoc | YARD | RDoc |
+| --- | --- | --- | --- |
+| Output | Markdown files | HTML site, `yri` | HTML site, `ri` |
+| Viewing | GitHub, any markdown previewer | Browser, `yard server` | Browser, `ri` |
+| Comment syntax | YARD tags (`@param`, `@return`, ...) | YARD tags | Prose and directives (`:call-seq:`, `:nodoc:`) |
+| Comment markup | Markdown, passed through | Markdown, RDoc, and others, converted to HTML | RDoc or Markdown, converted to HTML |
+| Ruby parser | [Prism](https://github.com/ruby/prism) | Its own | Prism (as of RDoc 8.1) |
+| Macros and directives | Through YARD, with `--yard-macros` | Yes | No |
+| Plugins and templates | No | Yes | Yes |
+| C extensions | No | Yes | Yes |
+| Ships with Ruby | No | No | Yes |
+
+**What is the same as YARD.** The tags, the `[Types]` syntax, references in
+braces, `(see Other#method)`, `@overload`, `@private`, and `@api private`, and
+stitching in extra files. A codebase documented for YARD needs no changes.
+Boondoc understands classes, modules, methods, attributes, constants,
+visibility in all its forms, `module_function`, aliases, mixins, `Struct.new`,
+`Data.define` and `Class.new`.
+
+**What is different from YARD.** There is no HTML, no server, no `.yardoc`
+database, no `yri`, no `yard stats`, and no template system. Boondoc does not
+load YARD plugins, and reads only part of `.yardopts` (see
+[below](#reading-yardopts)). Docstrings are treated as markdown and
+are not converted from RDoc markup or Textile. Macros and directives need the
+bridge described below.
+
+**How it relates to RDoc.** RDoc is the tool that ships with Ruby. It does
+not use YARD's tags, so comments written for RDoc carry less structure. Boondoc
+will still document such a codebase: every class and method gets a page and a
+signature, comments appear as written, and `:nodoc:` is honoured. RDoc markup
+such as `+code+` or `=== Heading` is left as it is rather than converted.
+
+### Reading `.yardopts`
+
+If the project has a `.yardopts`, Boondoc uses these options from it, so a
+codebase set up for YARD needs no extra configuration:
+
+| In `.yardopts` | Used as |
+| --- | --- |
+| source globs and directories | `sources` |
+| files after `-`, and `--files a,b` | `files` |
+| `-r`, `--readme`, `--main` | `readme` |
+| `--asset FROM[:DIR]` | `assets` |
+| `--title` | `title` |
+| `--private`, `--protected` | `private`, `protected` |
+| `--exclude REGEXP` | Ruby files whose path matches the regular expression are left out, as in YARD |
+
+`.boondoc.yml` and the command line win over `.yardopts`, one option at a time:
+a `files` list in `.boondoc.yml` replaces the one from `.yardopts` instead of
+adding to it. Pass `--no-yardopts`, or set `yardopts: false`, to skip the file.
+
+Boondoc does not use `--output-dir`. In a `.yardopts` it names YARD's HTML
+directory, which is usually ignored by git, while Boondoc's output is meant to be
+committed. Following it could send the docs somewhere that is never published,
+so Boondoc keeps writing to `output` (default `docs`) and prints a note. Set
+`output` in `.boondoc.yml`, or pass `-o`, to choose the directory. Every other
+option it does not use, such as `--markup`, `--plugin`, or `--template`, is listed
+in a note too, as are C source globs, since Boondoc documents Ruby only. The notes
+are not warnings, so `--strict` does not fail on them, and `--quiet` hides them.
+`.document` files are not read.
+
+`.yardopts` comes from the project, so it has the same limits as `.boondoc.yml`:
+its paths must be inside the project, and it cannot set the output directory.
+
+### Macros and directives
+
+Boondoc does not expand YARD macros and directives (`@!macro`, `@!method`,
+`@!attribute`) on its own. If your code relies on them, add the yard gem and
+pass `--yard-macros`:
+
+```ruby
+gem 'yard', group: :development
+```
+
+Prism remains the source of truth. YARD is run as a second pass and only
+contributes the objects that directives create and the expanded docstrings of
+comments that use a macro.
+
+### Performance
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="images/benchmark-dark.svg">
+  <img alt="Bar charts of the benchmark table in docs/Performance.md, one panel per codebase: Boondoc is the fastest tool on every codebase" src="images/benchmark-light.svg">
+</picture>
+
+The full table and how it was measured are in [docs/Performance.md](docs/Performance.md).
+
+## Development
+
+```sh
+bin/setup
+bundle exec rake          # specs and RuboCop
+bundle exec boondoc       # regenerate docs/ with boondoc itself
+bundle exec guard         # RuboCop, specs and a benchmark check on every change
+```
+
+The rendering specs compare against the files in
+`spec/fixtures/sample/expected`. After an intended change to the output,
+regenerate them with `UPDATE_GOLDEN=1 bundle exec rspec spec/boondoc/generator_spec.rb`
+and review the diff.
+
+New to the codebase? The [contributor familiarity guide](docs/CONTRIBUTING.md)
+walks through the pipeline and where to start for common changes.
+
+## License
+
+Available as open source under the terms of the [MIT License](LICENSE.txt).

data/exe/boondoc

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'boondoc'
+
+Boondoc::CLI.start_with_default(ARGV)

data/lib/boondoc/assets.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+require 'pathname'
+
+module Boondoc
+  # The files that are copied into the output directory next to the pages: images, video, PDFs,
+  # and anything else a page links to or embeds.
+  #
+  # Two kinds are copied. The ones named by the `assets` option are always copied. Each entry is a
+  # file, a directory (everything under it), or a glob, optionally followed by `:DIR` to copy into
+  # that directory of the output instead of keeping the project path. Hidden files, symlinks that
+  # leave the project, and anything in the output directory are skipped. With `copy_linked_assets`
+  # the files that pages embed are copied too, as they are found while the pages are rendered, so
+  # {#files} is only complete once rendering has finished.
+  class Assets
+    # @param config [Config]
+    # @raise [Error] when a named file is outside the project, or two files would be copied to the same path
+    def initialize(config)
+      @config = config
+      @named = Array(config.assets).each_with_object({}) { |entry, map| add(map, entry) }
+      @by_source = @named.invert
+      @linked = {}
+    end
+
+    # Where a file will be in the output directory, when it is copied there.
+    #
+    # @param absolute [String] absolute path of a file in the project
+    # @param embedded [Boolean] whether the page embeds the file, as an image does
+    # @return [String, nil] the path relative to the output directory, or nil when the file is not copied
+    def output_for(absolute, embedded: false)
+      @by_source[absolute] || (link(absolute) if embedded && @config.copy_linked_assets)
+    end
+
+    # Finds the copy of a path written in a page. A path is first read relative to the output
+    # directory, as YARD's `--asset` paths are, and then relative to the project.
+    #
+    # @param path [String] a path without any fragment or query
+    # @param embedded [Boolean] whether the page embeds the file rather than linking to it
+    # @return [String, nil] the path relative to the output directory, or nil when nothing is copied
+    def copy_for(path, embedded: false)
+      output = Pathname.new(path).cleanpath.to_s
+      return output if @named.key?(output)
+
+      output_for(File.expand_path(path, @config.root), embedded: embedded)
+    end
+
+    # @return [Hash{String => String}] absolute source paths, keyed by the path relative to
+    #   the output directory that each is copied to
+    def files
+      @named.merge(@linked)
+    end
+
+    private
+
+    def add(map, entry)
+      from, directory = entry.split(':', 2)
+      Dir.glob(from, base: @config.root).each do |match|
+        sources(match).each do |source, within|
+          output = directory ? output_path(directory, within) : source
+          absolute = File.expand_path(source, @config.root)
+          clash = map.fetch(output, absolute) != absolute
+          raise Error, "#{output} would be copied from both #{map[output]} and #{absolute}" if clash
+
+          map[output] = absolute
+        end
+      end
+    end
+
+    # @return [Array<Array(String, String)>] each file under a match, as its path in the project and
+    #   its path relative to the match, which a `:DIR` destination keeps
+    def sources(match)
+      full = File.expand_path(match, @config.root)
+      raise Error, "#{match} is outside the project (#{@config.root})" unless Containment.inside?(full, @config.root)
+      return [[relative(full), File.basename(full)]] if File.file?(full)
+
+      Dir.glob('**/*', base: full).select { |path| named_file?(File.join(full, path)) }
+         .map { |path| [relative(File.join(full, path)), path] }
+    end
+
+    def named_file?(full)
+      inside = full.delete_prefix(File.join(@config.root, ''))
+      File.file?(full) && inside.split('/').none? { |part| part.start_with?('.') } &&
+        Containment.inside?(full, @config.root) && !full.start_with?(File.join(@config.output_dir, ''))
+    end
+
+    def output_path(directory, within)
+      path = Pathname.new(File.join(directory, within)).cleanpath.to_s
+      raise Error, "asset destination #{directory} is outside the output directory" if path.start_with?('..', '/')
+
+      path
+    end
+
+    def relative(full)
+      Pathname.new(full).relative_path_from(Pathname.new(@config.root)).to_s
+    end
+
+    # Remembers an embedded file that is worth copying and returns where it goes.
+    def link(absolute)
+      root = File.join(@config.root, '')
+      return nil unless absolute.start_with?(root) && copyable?(absolute)
+
+      output = absolute.delete_prefix(root)
+      @linked[output] = absolute
+      output
+    end
+
+    def copyable?(absolute)
+      File.file?(absolute) && !Stitcher::MARKDOWN.match?(absolute) &&
+        !absolute.start_with?(File.join(@config.output_dir, '')) && Containment.inside?(absolute, @config.root)
+    end
+  end
+end

data/lib/boondoc/cli.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+require 'thor'
+
+module Boondoc
+  # The `boondoc` command.
+  class CLI < Thor
+    COMMANDS = %w[generate serve version help].freeze
+    COMMAND_FLAGS = %w[-h --help -v --version].freeze
+
+    # Runs the CLI, treating a bare `boondoc [GLOBS]` as `boondoc generate [GLOBS]`.
+    #
+    # @param argv [Array<String>]
+    # @return [void]
+    def self.start_with_default(argv)
+      known = COMMANDS.include?(argv.first) || COMMAND_FLAGS.include?(argv.first)
+      start(known ? argv : ['generate', *argv])
+    end
+
+    # @return [Boolean] exit non-zero when a command fails
+    def self.exit_on_failure?
+      true
+    end
+
+    desc 'generate [GLOBS]', 'Write markdown documentation (default command)'
+    long_desc <<~DESC
+      Parses the Ruby files matching GLOBS (default: lib/**/*.rb) and writes one markdown
+      file per class or module, plus an index, into the output directory.
+
+      Options can also be set in .boondoc.yml using the same names with underscores
+      (sources, exclude, output, index, readme, files, assets, copy_linked_assets, title, private,
+      protected, yard_macros, strict, yardopts). allow_outside_output can only be given on the command line.
+
+      The output directory must be inside the project, and not reached through a symlink.
+      Sources outside the project are skipped with a warning.
+    DESC
+    option :output, aliases: '-o', type: :string, desc: 'Output directory (default: docs)'
+    option :index, type: :string, desc: 'Name of the index page (default: README.md)'
+    option :readme, type: :string, desc: 'File to use as the index page (default: README.md if present)'
+    option :skip_readme, type: :boolean, desc: 'Do not include a README in the index page'
+    option :files, type: :array, desc: 'Extra markdown files or globs to stitch in'
+    option :assets, type: :array, desc: 'Files, directories, or globs to copy into the output (FROM or FROM:DIR)'
+    option :copy_linked_assets, type: :boolean,
+                                desc: 'Also copy the files that pages embed, such as images in the README'
+    option :exclude, type: :array, desc: 'Ruby files or globs to leave out'
+    option :title, type: :string, desc: 'Title for the index page when there is no README'
+    option :private, type: :boolean, desc: 'Include private methods and @private objects'
+    option :protected, type: :boolean, desc: 'Include protected methods'
+    option :yard_macros, type: :boolean, desc: 'Expand @!macro, @!method, and @!attribute using the yard gem'
+    option :yardopts, type: :boolean, desc: 'Read .yardopts (default; --no-yardopts to skip it)'
+    option :strict, type: :boolean, desc: 'Exit non-zero if there are warnings'
+    option :force, type: :boolean, desc: 'Overwrite files in the output directory that boondoc did not write'
+    option :allow_outside_output, type: :boolean,
+                                  desc: 'Allow an output directory outside the project (a security risk if the ' \
+                                        'project is not trusted; for docs kept outside the repository)'
+    option :config, aliases: '-c', type: :string, desc: 'Config file (default: .boondoc.yml)'
+    option :quiet, aliases: '-q', type: :boolean, desc: 'Only print warnings and errors'
+    def generate(*globs)
+      Generator.new(Config.load(overrides(globs))).run
+    rescue Error => e
+      raise Thor::Error, "boondoc: #{e.message}"
+    end
+
+    desc 'serve', 'Preview the generated docs in a browser with gh markdown-preview'
+    long_desc <<~DESC
+      Starts the gh markdown-preview extension of the GitHub CLI from inside the output
+      directory, so the links between pages work. Offers to install the extension when
+      it is missing. Run `boondoc` first to generate the docs.
+    DESC
+    option :output, aliases: '-o', type: :string, desc: 'Directory holding the docs (default: docs)'
+    option :allow_outside_output, type: :boolean, desc: 'Allow a docs directory outside the project'
+    option :host, type: :string, default: Preview::DEFAULT_HOST, desc: 'Address to bind'
+    option :port, aliases: '-p', type: :numeric, desc: 'Port to listen on (default: 3333)'
+    option :config, aliases: '-c', type: :string, desc: 'Config file (default: .boondoc.yml)'
+    def serve
+      config = Config.load(options.slice('output', 'config', 'allow_outside_output').transform_keys(&:to_sym))
+      Preview.new(config.output_dir, host: options[:host], port: options[:port]) do
+        yes?("The gh markdown-preview extension is not installed. Install #{Preview::EXTENSION} now? [y/N]")
+      end.start
+    rescue Error => e
+      raise Thor::Error, "boondoc: #{e.message}"
+    end
+
+    desc 'version', 'Print the boondoc version'
+    def version
+      puts Boondoc::VERSION
+    end
+    map %w[-v --version] => :version
+
+    private
+
+    def overrides(globs)
+      settings = options.to_h.transform_keys(&:to_sym)
+      settings[:readme] = false if settings.delete(:skip_readme)
+      settings[:sources] = globs unless globs.empty?
+      settings
+    end
+  end
+end