{"id":17988512,"url":"https://github.com/heyvito/docrb","last_synced_at":"2025-10-08T16:55:50.925Z","repository":{"id":72188657,"uuid":"420543533","full_name":"heyvito/docrb","owner":"heyvito","description":"📖 An opinionated documentation generator for Ruby ","archived":false,"fork":false,"pushed_at":"2024-10-28T17:06:38.000Z","size":593,"stargazers_count":16,"open_issues_count":1,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-10-07T16:13:06.951Z","etag":null,"topics":["documentation","documentation-generator","documentation-tool","ruby"],"latest_commit_sha":null,"homepage":"","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/heyvito.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2021-10-23T23:18:37.000Z","updated_at":"2025-10-06T09:12:13.000Z","dependencies_parsed_at":null,"dependency_job_id":"e72ce473-94f6-421e-9493-968d8395ba0c","html_url":"https://github.com/heyvito/docrb","commit_stats":{"total_commits":44,"total_committers":2,"mean_commits":22.0,"dds":"0.13636363636363635","last_synced_commit":"fcf4ddfc8dd76cb555604f7230c8c04212c6c436"},"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/heyvito/docrb","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/heyvito%2Fdocrb","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/heyvito%2Fdocrb/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/heyvito%2Fdocrb/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/heyvito%2Fdocrb/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/heyvito","download_url":"https://codeload.github.com/heyvito/docrb/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/heyvito%2Fdocrb/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":278981512,"owners_count":26079640,"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","status":"online","status_checked_at":"2025-10-08T02:00:06.501Z","response_time":56,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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","documentation-generator","documentation-tool","ruby"],"created_at":"2024-10-29T19:11:54.762Z","updated_at":"2025-10-08T16:55:50.897Z","avatar_url":"https://github.com/heyvito.png","language":"Ruby","readme":"![docrb-logo](https://user-images.githubusercontent.com/77198/138565209-ad6fad7f-ff60-4f60-9fe0-625de690c00d.png)\n\u003chr /\u003e\n\nDocrb is an opinionated documentation generator for Ruby projects. It works by\nparsing source-code and comments preceding classes, modules, attributes, and\nmethods, and generates a static website with its findings. You can check\n[Logrb's documentation](https://heyvito.github.io/logrb) to see Docrb\nin action!\n\n\u003e **Beta quality!** Hey there! As far as we are already using Docrb on a few\nprojects (some private, some public), there may still be some rough edges. In\ncase you run into any issue, please do tell us using GitHub's issue tracker! 💕\n\n## Installing\n\nInstall `docrb` by adding it to your bundle. Remember to place it in your development/test group, and to not auto\nrequire it!\n\n```ruby\ngroup :development, :test do\n  gem \"docrb\", require: false\nend\n\n# or...\n\ngem \"docrb\", require: false\n```\n\n## Using\n\nAs mentioned in the previous section, Docrb is an **opinionated** documentation\ngenerator. This means that it uses a specific formatting in order to infer\nmethods, annotations and references. As long as your project adheres to those\nconventions, Docrb will be able to automatically generate and augment your\ndocumentation.\n\n#### Simple Example\n\n```ruby\n\n# Internal: foo raises an ZeroDivisionError\ndef foo\n  3 / 0\nend\n```\n\nThe block above will be enough to emit a documentation for it including a label\nindicating the method is considered to be \"Internal\". The following prefixes\nare handled by Docrb automatically:\n\n- Private\n- Public\n- Internal\n- Deprecated\n\nAs long as a documentation block begins with one of the keywords above (case\ninsensitive) followed by a colon, Docrb will annotate the method accordingly.\n\n#### Documenting parameters\n\nWhen documenting parameters, just place a blank line between the main\ndocumentation, followed by an **aligned** list of parameters. For instance:\n\n```ruby\n# Greets a provided name with an optional greeting\n#\n# name      - The person's name\n# greeting: - The greeting to use. Defaults to \"Oi\"\ndef greet(name, greeting: nil)\n  greeting ||= \"Oi\"\n  \"#{greeting} #{name}\"\nend\n```\n\n#### Adding code examples\n\nDocrb can highlight code examples automatically too! Just add an extra\nindentation level to create a code example block:\n\n```ruby\n# Greets a provided name with an optional greeting\n#\n# name      - The person's name\n# greeting: - The greeting to use. Defaults to \"Oi\"\n#\n# Usage example:\n#\n#   greet(\"Fefo\", \"Aye\")\n#   # =\u003e Aye Fefo\ndef greet(name, greeting: nil)\n  greeting ||= \"Oi\"\n  \"#{greeting} #{name}\"\nend\n```\n\n#### Adding references\nDocrb automatically searches for references to other methods and classes/modules.\nThe following patterns are assumed as references and linked automatically:\n\n - `#method_name`\n - `ModuleOrClass.method_name`\n - `ModuleOrClass#method_name`\n - `ModuleOrClass::ChildModuleOrClass.method_name`\n - `ModuleOrClass::ChildModuleOrClass#method_name`\n - `::SomeRootClass#method_name`\n - `::SomeRootClass.method_name`\n - `::SomeRootClass.method_name`\n - `ModuleOrClass`\n - `ModuleOrClass::ChildModuleOrClass`\n - `::ModuleOrClass`\n\n## Generating Documentation\n\nSimply `cd` to your project's directory, and invoke the `docrb` utility.\nFor instance, the following command line is used to generate Logrb's\ndocumentation, which is then generated on an `output` directory:\n\n```bash\n$ docrb -blib . output\n```\n\nThe tool can usually detect all it needs, but if needed, extra options may\nbe provided:\n\n```\n$ docrb --help\n\nUsage: bin/docrb [options] [input directory] [output directory]\n        --help                       Prints this help\n    -b, --base=PATH                  Base directory to search for source files. Defaults to the provided input directory.\n    -r, --readme=PATH                Path for README.md file. When omitted, Docrb searches for a README.md file in the provided input directory.\n    -n, --name=NAME                  Name of the project being documented. When omitted, Docrb attempts to extract information from a .gemspec file in the provided input directory.\n    -s, --summary=SUMMARY            Short summary of the project being documented. When omitted, Docrb attempts to extract information from a .gemspec file in the provided input directory.\n    -h, --host=URL                   URL for the gem's hosted URL. When omitted, Docrb attempts to extract information from a .gemspec file in the provided input directory.\n    -g, --git-repo=URL               URL for the repository containing the documented project. When omitted, Docrb attempts to extract this information from the .git directory present in the provided input directory, if any.\n        --authors a,b,c              List of name of project authors. When omitted, Docrb attempts to extract information from a .gemspec file in the provided input directory.\n    -l, --license=LICENSE            The project's license. When omitted, Docrb attempts to extract information from a .gemspec file in the provided input directory.\n```\n\n## Contributing\n\nYay! Contributions are more than welcome!\nSee [CONTRIBUTING.md](CONTRIBUTING.md) to get a summary on how to hack Docrb.\nAlso, ensure to take a look at our [code of conduct](CODE_OF_CONDUCT.md)!\nEveryone interacting in the Docrb project's codebases, issue trackers,\nchat rooms, and mailing lists is expected to follow it. Rule of thumb: be nice.\n\n## License\n\n```\nThe MIT License (MIT)\n\nCopyright (c) 2021-2024 Vito Sartori\n\nPermission is hereby granted, free of charge, to any person obtaining a copy\nof this software and associated documentation files (the \"Software\"), to deal\nin the Software without restriction, including without limitation the rights\nto use, copy, modify, merge, publish, distribute, sublicense, and/or sell\ncopies of the Software, and to permit persons to whom the Software is\nfurnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in\nall copies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN\nTHE SOFTWARE.\n\n```\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fheyvito%2Fdocrb","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fheyvito%2Fdocrb","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fheyvito%2Fdocrb/lists"}