{"id":13463174,"url":"https://github.com/lsegal/yard","last_synced_at":"2025-05-13T18:04:46.446Z","repository":{"id":428087,"uuid":"1252","full_name":"lsegal/yard","owner":"lsegal","description":"YARD is a Ruby Documentation tool. The Y stands for \"Yay!\"","archived":false,"fork":false,"pushed_at":"2024-12-20T22:27:47.000Z","size":8967,"stargazers_count":1969,"open_issues_count":118,"forks_count":406,"subscribers_count":44,"default_branch":"main","last_synced_at":"2025-05-06T16:17:23.883Z","etag":null,"topics":["documentation","rdoc","ruby","ruby-documentation","tool","yard","yardoc"],"latest_commit_sha":null,"homepage":"http://yardoc.org","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/lsegal.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":"lsegal"}},"created_at":"2008-02-26T00:01:52.000Z","updated_at":"2025-05-06T04:00:39.000Z","dependencies_parsed_at":"2023-07-05T14:54:04.185Z","dependency_job_id":"545ddfb6-2cf0-4fbf-bf15-885f7590c849","html_url":"https://github.com/lsegal/yard","commit_stats":{"total_commits":3652,"total_committers":165,"mean_commits":"22.133333333333333","dds":0.1801752464403067,"last_synced_commit":"3c14200e0af277e38cf889eef59bf808d309c43e"},"previous_names":[],"tags_count":92,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lsegal%2Fyard","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lsegal%2Fyard/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lsegal%2Fyard/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lsegal%2Fyard/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/lsegal","download_url":"https://codeload.github.com/lsegal/yard/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253240351,"owners_count":21876593,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["documentation","rdoc","ruby","ruby-documentation","tool","yard","yardoc"],"created_at":"2024-07-31T13:00:47.337Z","updated_at":"2025-05-13T18:04:46.415Z","avatar_url":"https://github.com/lsegal.png","language":"Ruby","readme":"# YARD: Yay! A Ruby Documentation Tool\n\n[![Homepage](https://img.shields.io/badge/home-yardoc.org-blue.svg)](http://yardoc.org)\n[![GitHub](https://img.shields.io/badge/github-lsegal/yard-blue.svg)](http://github.com/lsegal/yard)\n[![Documentation](https://img.shields.io/badge/docs-rdoc.info-blue.svg)](http://rubydoc.org/gems/yard/frames)\n\n[![Gem Version](https://badge.fury.io/rb/yard.svg)](http://github.com/lsegal/yard/releases)\n[![Unit Tests](https://github.com/lsegal/yard/actions/workflows/ci.yml/badge.svg)](https://github.com/lsegal/yard/actions/workflows/ci.yml)\n[![Coverage Status](https://coveralls.io/repos/github/lsegal/yard/badge.svg)](https://coveralls.io/github/lsegal/yard)\n[![License](https://img.shields.io/badge/license-MIT-yellowgreen.svg)](#license)\n\n## Synopsis\n\nYARD is a documentation generation tool for the Ruby programming language. It\nenables the user to generate consistent, usable documentation that can be\nexported to a number of formats very easily, and also supports extending for\ncustom Ruby constructs such as custom class level definitions. Below is a\nsummary of some of YARD's notable features.\n\n## Feature List\n\n**1. RDoc/SimpleMarkup Formatting Compatibility**: YARD is made to be compatible\nwith RDoc formatting. In fact, YARD does no processing on RDoc documentation\nstrings, and leaves this up to the output generation tool to decide how to\nrender the documentation.\n\n**2. Yardoc Meta-tag Formatting Like Python, Java, Objective-C and other\nlanguages**: YARD uses a '@tag' style definition syntax for meta tags alongside\nregular code documentation. These tags should be able to happily sit side by\nside RDoc formatted documentation, but provide a much more consistent and usable\nway to describe important information about objects, such as what parameters\nthey take and what types they are expected to be, what type a method should\nreturn, what exceptions it can raise, if it is deprecated, etc.. It also allows\ninformation to be better (and more consistently) organized during the output\ngeneration phase. You can find a list of tags in the {file:docs/Tags.md#taglist\nTags.md} file.\n\nYARD also supports an optional \"types\" declarations for certain tags. This\nallows the developer to document type signatures for ruby methods and parameters\nin a non intrusive but helpful and consistent manner. Instead of describing this\ndata in the body of the description, a developer may formally declare the\nparameter or return type(s) in a single line. Consider the following method\ndocumented with YARD formatting:\n\n```ruby\n# Reverses the contents of a String or IO object.\n#\n# @param contents [String, #read] the contents to reverse\n# @return [String] the contents reversed lexically\ndef reverse(contents)\n  contents = contents.read if contents.respond_to? :read\n  contents.reverse\nend\n```\n\nWith the above @param tag, we learn that the contents parameter can either be a\nString or any object that responds to the 'read' method, which is more powerful\nthan the textual description, which says it should be an IO object. This also\ninforms the developer that they should expect to receive a String object\nreturned by the method, and although this may be obvious for a 'reverse' method,\nit becomes very useful when the method name may not be as descriptive.\n\n**3. Custom Constructs and Extensibility of YARD**: YARD is designed to be\nextended and customized by plugins. Take for instance the scenario where you\nneed to document the following code:\n\n```ruby\nclass List\n # Sets the publisher name for the list.\n cattr_accessor :publisher\nend\n```\n\nThis custom declaration provides dynamically generated code that is hard for a\ndocumentation tool to properly document without help from the developer. To ease\nthe pains of manually documenting the procedure, YARD can be extended by the\ndeveloper to handle the `cattr_accessor` construct and automatically create an\nattribute on the class with the associated documentation. This makes documenting\nexternal API's, especially dynamic ones, a lot more consistent for consumption\nby the users.\n\nYARD is also designed for extensibility everywhere else, allowing you to add\nsupport for new programming languages, new data structures and even where/how\ndata is stored.\n\n**4. Raw Data Output**: YARD also outputs documented objects as raw data (the\ndumped Namespace) which can be reloaded to do generation at a later date, or\neven auditing on code. This means that any developer can use the raw data to\nperform output generation for any custom format, such as YAML, for instance.\nWhile YARD plans to support XHTML style documentation output as well as command\nline (text based) and possibly XML, this may still be useful for those who would\nlike to reap the benefits of YARD's processing in other forms, such as throwing\nall the documentation into a database. Another useful way of exploiting this raw\ndata format would be to write tools that can auto generate test cases, for\nexample, or show possible unhandled exceptions in code.\n\n**5. Local Documentation Server**: YARD can serve documentation for projects or\ninstalled gems (similar to `gem server`) with the added benefit of dynamic\nsearching, as well as live reloading. Using the live reload feature, you can\ndocument your code and immediately preview the results by refreshing the page;\nYARD will do all the work in re-generating the HTML. This makes writing\ndocumentation a much faster process.\n\n## Installing\n\nTo install YARD, use the following command:\n\n```sh\n$ gem install yard\n```\n\n(Add `sudo` if you're installing under a POSIX system as root)\n\nAlternatively, if you've checked the source out directly, you can call\n`rake install` from the root project directory.\n\n**Important Note for Debian/Ubuntu users:** there's a possible chance your Ruby\ninstall lacks RDoc, which is occasionally used by YARD to convert markup to\nHTML. If running `which rdoc` turns up empty, install RDoc by issuing:\n\n```sh\n$ sudo apt-get install rdoc\n```\n\n### Markdown parser\n\nWhen rendering markdown, yard will use one of several possible markdown providers,\n[in order of priority](https://github.com/lsegal/yard/blob/e833aac7a01510245dd4ae1d1d18b046c8293c2d/lib/yard/templates/helpers/markup_helper.rb#L26-L33).\nIf you are experiencing rendering bugs (example [1](https://github.com/lsegal/yard/issues/1410) [2](https://github.com/lsegal/yard/issues/1543)), try adding one of the\ngems further up in the list to your Gemfile.\n\n## Usage\n\nThere are a couple of ways to use YARD. The first is via command-line, and the\nsecond is the Rake task.\n\n### 1. yard Command-line Tool\n\nYARD comes packaged with a executable named `yard` which can control the many\nfunctions of YARD, including generating documentation, graphs running the YARD\nserver, and so on. To view a list of available YARD commands, type:\n\n```sh\n$ yard --help\n```\n\nPlugins can also add commands to the `yard` executable to provide extra\nfunctionality.\n\n#### Generating Documentation\n\n\u003cspan class=\"note\"\u003eThe `yardoc` executable is a shortcut for `yard doc`.\u003c/span\u003e\n\nThe most common command you will probably use is `yard doc`, or `yardoc`. You\ncan type `yardoc --help` to see the options that YARD provides, but the easiest\nway to generate docs for your code is to simply type `yardoc` in your project\nroot. This will assume your files are located in the `lib/` directory. If they\nare located elsewhere, you can specify paths and globs from the commandline via:\n\n```sh\n$ yardoc 'lib/**/*.rb' 'app/**/*.rb' ...etc...\n```\n\nThe tool will generate a `.yardoc` file which will store the cached database of\nyour source code and documentation. If you want to re-generate your docs with\nanother template you can simply use the `--use-cache` (or -c) option to speed up\nthe generation process by skipping source parsing.\n\nYARD will by default only document code in your public visibility. You can\ndocument your protected and private code by adding `--protected` or `--private`\nto the option switches. In addition, you can add `--no-private` to also ignore\nany object that has the `@private` meta-tag. This is similar to RDoc's \":nodoc:\"\nbehaviour, though the distinction is important. RDoc implies that the object\nwith :nodoc: would not be documented, whereas YARD still recommends documenting\nprivate objects for the private API (for maintainer/developer consumption).\n\nYou can also add extra informative files (README, LICENSE) by separating the\nglobs and the filenames with '-'.\n\n```sh\n$ yardoc 'app/**/*.rb' - README LICENSE FAQ\n```\n\nIf no globs precede the '-' argument, the default glob (`lib/**/*.rb`) is used:\n\n```sh\n$ yardoc - README LICENSE FAQ\n```\n\nNote that the README file can be specified with its own `--readme` switch.\n\nYou can also add a `.yardopts` file to your project directory which lists the\nswitches separated by whitespace (newlines or space) to pass to yardoc whenever\nit is run. A full overview of the `.yardopts` file can be found in\n[YARD::CLI::Yardoc](https://rubydoc.info/gems/yard/YARD/CLI/Yardoc#label-Options+File+-28.yardopts-29).\n\n#### Queries\n\nThe `yardoc` tool also supports a `--query` argument to only include objects\nthat match a certain data or meta-data query. The query syntax is Ruby, though a\nfew shortcuts are available. For instance, to document only objects that have an\n\"@api\" tag with the value \"public\", all of the following syntaxes would give the\nsame result:\n\n```sh\n--query '@api.text == \"public\"'\n--query 'object.has_tag?(:api) \u0026\u0026 object.tag(:api).text == \"public\"'\n--query 'has_tag?(:api) \u0026\u0026 tag(:api).text == \"public\"'\n```\n\nNote that the \"@tag\" syntax returns the first tag named \"tag\" on the object. To\nreturn the array of all tags named \"tag\", use \"@@tag\".\n\nMultiple `--query` arguments are allowed in the command line parameters. The\nfollowing two lines both check for the existence of a return and param tag:\n\n```sh\n--query '@return' --query '@param'\n--query '@return \u0026\u0026 @param'\n```\n\nFor more information about the query syntax, see the {YARD::Verifier} class.\n\n### 2. Rake Task\n\nThe second most obvious is to generate docs via a Rake task. You can do this by\nadding the following to your `Rakefile`:\n\n```ruby\nrequire 'yard'\n\nYARD::Rake::YardocTask.new do |t|\n t.files   = ['lib/**/*.rb', OTHER_PATHS]   # optional\n t.options = ['--any', '--extra', '--opts'] # optional\n t.stats_options = ['--list-undoc']         # optional\nend\n```\n\nAll the settings: `files`, `options` and `stats_options` are optional. `files`\nwill default to `lib/**/*.rb`, `options` will represents any options you might\nwant to add and `stats_options` will pass extra options to the stats command.\nAgain, a full list of options is available by typing `yardoc --help` in a shell.\nYou can also override the options at the Rake command-line with the OPTS\nenvironment variable:\n\n```sh\n$ rake yard OPTS='--any --extra --opts'\n```\n\n### 3. `yri` RI Implementation\n\nThe yri binary will use the cached .yardoc database to give you quick ri-style\naccess to your documentation. It's way faster than ri but currently does not\nwork with the stdlib or core Ruby libraries, only the active project. Example:\n\n```sh\n$ yri YARD::Handlers::Base#register\n$ yri File.relative_path\n```\n\nNote that class methods must not be referred to with the \"::\" namespace\nseparator. Only modules, classes and constants should use \"::\".\n\nYou can also do lookups on any installed gems. Just make sure to build the\n.yardoc databases for installed gems with:\n\n```sh\n$ yard gems\n```\n\nIf you don't have sudo access, it will write these files to your `~/.yard`\ndirectory. `yri` will also cache lookups there.\n\n### 4. `yard server` Documentation Server\n\nThe `yard server` command serves documentation for a local project or all\ninstalled RubyGems. To serve documentation for a project you are working on,\nsimply run:\n\n```sh\n$ yard server\n```\n\nAnd the project inside the current directory will be parsed (if the source has\nnot yet been scanned by YARD) and served at\n[http://localhost:8808](http://localhost:8808).\n\n#### Live Reloading\n\nIf you want to serve documentation on a project while you document it so that\nyou can preview the results, simply pass `--reload` (`-r`) to the above command\nand YARD will reload any changed files on each request. This will allow you to\nchange any documentation in the source and refresh to see the new contents.\n\n#### Serving Gems\n\nTo serve documentation for all installed gems, call:\n\n```sh\n$ yard server --gems\n```\n\nThis will also automatically build documentation for any gems that have not been\npreviously scanned. Note that in this case there will be a slight delay between\nthe first request of a newly parsed gem.\n\n### 5. `yard graph` Graphviz Generator\n\nYou can use `yard graph` to generate dot graphs of your code. This, of course,\nrequires [Graphviz](http://www.graphviz.org) and the `dot` binary. By default\nthis will generate a graph of the classes and modules in the best UML2 notation\nthat Graphviz can support, but without any methods listed. With the `--full`\noption, methods and attributes will be listed. There is also a `--dependencies`\noption to show mixin inclusions. You can output to stdout or a file, or pipe\ndirectly to `dot`. The same public, protected and private visibility rules apply\nto `yard graph`. More options can be seen by typing `yard graph --help`, but\nhere is an example:\n\n```sh\n$ yard graph --protected --full --dependencies\n```\n\n## Changelog\n\nSee {file:CHANGELOG.md} for a list of changes.\n\n## License\n\nYARD \u0026copy; 2007-2020 by [Loren Segal](mailto:lsegal@soen.ca). YARD is licensed\nunder the MIT license except for some files which come from the RDoc/Ruby\ndistributions. Please see the {file:LICENSE} and {file:LEGAL} documents for more\ninformation.\n","funding_links":["https://github.com/sponsors/lsegal"],"categories":["Documentation Tools","Ruby","Happy Exploring 🤘","documentation","Documentation"],"sub_categories":["Documentation Generators"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flsegal%2Fyard","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flsegal%2Fyard","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flsegal%2Fyard/lists"}