whoami

Lucas Jenß

cat /etc/motd

The Coding Journal ツ — Notes taken on an epic coding journey. Technical solutions, debugging notes, and practical guides from the trenches of software development.

Close-up of white dominoes with black dots standing on green felt surface, shallow depth of field, focused mood

ls -la ~/languages/

total 8
drwxr-xr-x
▶ PHP
▶ Ruby
▶ Scala
▶ C#
▶ JavaScript
▶ Objective-C
▶ Shell Scripting

ls -la ~/toolchain/

total 7
drwxr-xr-x
▶ Typo3
▶ Akka
▶ Capistrano
▶ Git
▶ MAMP
▶ Adobe Illustrator
▶ NSTrackingArea (Cocoa)

uname -a

platforms
drwxr-xr-x
▶ Mac OS X
▶ Unix

Generate Ruby Docs With YARD And Capistrano

Good Ruby documentation reduces the time a team spends guessing how a class is intended to be used. YARD turns comments, method signatures, modules, and examples into a searchable HTML reference, giving developers a reliable view of a codebase without asking the original author to explain every detail.

For teams deploying applications across Australia, generated documentation can also become part of a dependable release routine. A developer in Sydney may publish before the Melbourne office starts its day, while a Perth colleague checks the result several hours later. Using YARD with Capistrano makes that process repeatable rather than dependent on a laptop, an undocumented command, or a last-minute arvo fix.

Why YARD Fits Ruby Projects

YARD is a Ruby documentation tool that understands common language structures and supports structured tags such as @param, @return, @raise, @example, and @see. It can generate HTML pages, produce Markdown-like output, and expose warnings when documentation refers to missing objects or malformed tags.

A simple method may be documented like this:

# Calculates the total including the supplied GST rate.
#
# @param amount [BigDecimal] amount before tax
# @param rate [BigDecimal] tax rate as a decimal
# @return [BigDecimal] amount including tax
def with_tax(amount, rate)
  amount + (amount * rate)
end

The value comes from writing comments where the behaviour is defined. A public service object, background job, or API client can explain its inputs and failures beside its implementation. That context is particularly useful in a growing consultancy or product team, where a new developer may inherit code written in a different project or framework.

YARD is also useful for troubleshooting habits. A note about an unusual callback or deployment assumption can prevent future confusion, much like a practical explanation of empty TYPO3 templates can save time when a framework appears to fail silently.

Preparing The Project For Documentation

Add YARD to the development dependencies in the Gemfile:

group :development do
  gem "yard"
end

Run Bundler, then create a basic documentation configuration:

bundle install
bundle exec yard init

The generated .yardopts file can contain options that keep output consistent between a developer workstation and the deployment server:

--markup markdown
--output-dir doc
--exclude spec
--exclude test
--no-private

--no-private keeps internal implementation details out of the public reference. That setting should be chosen deliberately: an internal engineering portal may need private methods, while customer-facing documentation should usually show only the supported API.

YARD depends on comments being clear and tags being accurate. Use @api public or @api private where the project needs an explicit boundary, and document yielded values with @yield and @yieldparam when a method accepts a block. Run bundle exec yard stats during development to see how much of the codebase is documented, but treat the percentage as a signal rather than a quality score.

Building A Repeatable YARD Task

The simplest build command is:

bundle exec yard doc

This scans the Ruby source and writes HTML files to doc/. A Rake task makes the operation easier to invoke from CI and Capistrano:

# lib/tasks/documentation.rake
namespace :docs do
  desc "Generate the YARD reference"
  task :build do
    sh "bundle exec yard doc --output-dir doc"
  end
end

A project can also use YARD’s Rake integration:

require "yard"

YARD::Rake::YardocTask.new do |t|
  t.files = ["lib/**/*.rb", "app/**/*.rb"]
  t.options = ["--output-dir", "doc", "--no-private"]
end

Choose one approach and keep it visible to contributors. If the application relies on Rails autoloading, avoid assuming that every runtime constant will be available while YARD parses files. Explicit source paths and straightforward comments are generally more dependable than documentation code that triggers application initialisation.

Warnings deserve attention. A missing constant may indicate a harmless dynamic pattern, or it may reveal a documentation link that users cannot follow. Run the task locally, inspect the generated index, and fail the build for serious warnings if the project treats reference documentation as a release artifact.

Connecting Capistrano To The Build

Capistrano 3 uses namespaced tasks and deployment hooks. A deployment can build documentation after the new release has been updated:

# lib/capistrano/tasks/yard.rake
namespace :deploy do
  desc "Generate YARD documentation"
  task :yard do
    on release_roles(:app) do
      within release_path do
        execute :bundle, :exec, :yard, :doc,
                "--output-dir", "doc",
                "--no-private"
      end
    end
  end

  after :published, :yard
end

The command runs inside release_path, so it uses the code and bundled gems belonging to that release. release_roles(:app) should match the servers that have the source code and Ruby environment required to build the reference. On a small Australian VPS, the app server and web server may be the same machine; in a larger Sydney or Melbourne setup, separating roles can avoid unnecessary work on a front-end host.

Capistrano loads task files from lib/capistrano/tasks, provided the deployment configuration requires the relevant recipes. Confirm that the production server has the correct Ruby version, Bundler settings, and native libraries. A documentation build can fail for reasons unrelated to YARD if a gem with a native extension cannot compile on the host.

For a more controlled workflow, build the HTML in CI and upload it as an artifact. This is often preferable when production servers are intentionally minimal or when deployments run through a managed platform. The key decision is whether documentation is generated from the exact release being served, rather than from an untracked local checkout.

Publishing Documentation Safely

Generated files should not be exposed accidentally through the application’s source tree. One practical pattern is to copy the finished output into a shared directory:

namespace :deploy do
  task :publish_docs do
    on release_roles(:app) do
      within release_path do
        execute :mkdir, "-p", shared_path.join("docs")
        execute :rsync, "-a", "doc/", shared_path.join("docs/")
      end
    end
  end

  after :yard, :publish_docs
end

If the web server can serve a shared directory, configure a stable URL such as /developer-docs. Another option is to symlink public/docs to shared/docs during deployment. Keep old generated files until the new release is verified, then remove stale content through a separate maintenance task rather than deleting it during a failed deployment.

Access control matters when the reference contains internal class names, business rules, or operational examples. Basic authentication, an IP allowlist, or a private object-storage bucket may be suitable. Australian organisations handling customer information should also consider where documentation is hosted and whether the chosen provider aligns with their privacy and contractual requirements.

A public project may publish docs to a static host, while an internal platform might use S3-compatible storage with a CloudFront-style distribution. Teams working across AEST, AEDT, and AWST should include the Git commit or release identifier on the documentation page so everyone can tell which version they are viewing.

Making Documentation Part Of Delivery

Capistrano can deploy the application and documentation together, but a release hook should not hide failures. If a YARD build fails after the application has been published, the team needs clear logs and a rollback policy. Run the same command in CI before production so syntax errors and broken references are caught earlier.

A useful pipeline might run:

bundle exec ruby -c lib/my_app/client.rb
bundle exec rspec
bundle exec yard doc --fail-on-warning

The exact YARD options depend on the installed version, so check them with bundle exec yard help. Some projects prefer warnings to be reported without failing a release because dynamic Ruby code can generate unavoidable notices. In that case, track the warning count and prevent it from increasing.

Documentation should describe stable behaviour rather than repeat every implementation detail. Include examples for public APIs, explain expected exceptions, and record configuration values without publishing secrets. If the system uses Akka or another distributed component, operational notes can be especially valuable; a guide to Akka cluster removal illustrates the kind of troubleshooting knowledge that belongs near the code’s operational boundary.

Keep the process friendly for contributors. A developer in Brisbane should be able to clone the repository, run one Bundler command, and generate the same pages as a deployment in Sydney. Pin the Ruby and gem versions, document the local command in the README, and use a small sample project when diagnosing YARD behaviour. The NixMash site is another useful example of a development-focused web resource where practical technical material can be kept close to the tools and workflows it discusses.

Add a YARD build to the release checklist, publish the generated reference through Capistrano, and display the deployed commit beside the pages. That small investment turns comments into a dependable engineering asset, giving Australian teams a shared reference that remains available after the original developer has moved to the next project.


cat ~/interests.json

KeyValue
editorTerminal-first workflow
osMac OS X / Unix
vcsGit, distributed version control
deployCapistrano, cron automation
graphicsSVG, Adobe Illustrator troubleshooting
networkingIP validation, SSH, VPN

git log --oneline --reverse

2013-10-30

Solving SVG import issues in Adobe Illustrator CS6 and CC

When importing an SVG into Illustrator, the operation fails with an unknown error [CANT]. A workaround for this Adobe-side bug.

2013

Solving NDK build issues on OS X

Troubleshooting native development kit compilation problems on Mac OS X.

2013

Programmatically adding PHP generated TypoScript to the backend configuration

Integrating dynamically generated TypoScript into Typo3 backend setups using PHP.

2013

ArgumentError: Could not parse PKey: no start line

Debugging an SSH key parsing error encountered during deployment.

2011-08-04

Validating IP-Addresses in PHP

Using PHP filter functions with flags like FILTER_FLAG_IPV4 and FILTER_FLAG_IPV6, and understanding how filter_var handles reserved IP addresses.

2011-07-09

Cocoa: Using NSTrackingArea

A short tutorial on using Cocoa's NSTrackingArea to capture mouseEntered and mouseExited events.


cat ~/contact.txt

github: github.com/x3ro
stackoverflow: x3ro
coderwall: coderwall.com/x3ro
twitter: @x3rames