Railsでのドキュメントワークフローの構築

RdocやYARDなどのドキュメントジェネレーターは、コードコメントから開発者向けドキュメントを生成します。 Rdocやその他の構文を受け入れるYARDを使用して、スタンドアロンのドキュメントサイトを作成できます。この例では、既存のJekyllサイトにYARDドキュメントを追加します。 Jekyllは、YARDによって生成された静的ファイルを/devなどのパスで公開できます。 。 YARDを単独で使用してドキュメントサイトを作成することもできます。

Railsがアプリを生成すると、いくつかの基本的なコードコメントも生成されます。

# app/controllers/posts_controller.rb

class PostsController < ApplicationController
  before_action :set_post, only: %i[ show edit update destroy ]

  # GET /posts or /posts.json
  def index
    @posts = Post.all
  end

  # GET /posts/1 or /posts/1.json
  def show
  end

  # GET /posts/new
  def new
    @post = Post.new
  end

  # GET /posts/1/edit
  def edit
  end

  # code omitted

end

YARDがこれらのコメントを使用してドキュメントサイトを作成する方法を確認するには、yard docを実行してください またはyardoc Railsアプリのルートディレクトリからのコマンド：

yardoc --output-dir docs/dev app/**/*.rb

yardocの場合 コマンドが機能しない場合は、bundle install yardを使用してYARDgemをインストールしてください 。

YARDは、出力ファイルをoutput-dirに配置します 、Jekyllディレクトリ/docs/devに設定されています 上記のコマンドで。 Jekyllは、ベースパスが/devのYARDのサイトファイルを公開できるようになりました。 。

RDocまたは他の構文（YARDのドキュメントを参照）を使用して、より複雑なドキュメントを作成できますが、ここでは既存のドキュメントを使用します。

Jekyllサーバーを起動し、localhost:4000/devに移動します YARDで生成されたドキュメントを表示するには：

現時点では、メインのJekyllサイトからこれらの開発者向けドキュメントに移動する方法はありません。 Jekyllサイトから開発者向けドキュメントへのリンクを追加するには、以下をdocs/_config.ymlに追加します。 ：

# Aux links for the upper right navigation
aux_links:
  "Developer Documentation":
    - "/dev"

これで、JekyllとYARDの説明は終わりです。ドキュメントサイトが設定されたので、開発者とライターは、Markdownファイル（またはコードコメント）にコンテンツを書き込んで、GitHubにプッシュするだけです。次のセクションでは、これらのドキュメントを継続的に公開して展開する方法について説明します。

Netlifyを使用した継続的な公開とデプロイ

ドキュメントへの変更が承認されてリポジトリにマージされると、ライブサイトが自動的に更新されるため、ドキュメントサイトでは継続的な公開が便利です。このチュートリアルでは、この目的でNetlifyを使用していますが、GitHub Pages、GitLab Pages、Firebaseなどの他のツールも利用できます。

これまでに構築してきたサイトは、Netlify：DocsSiteによってホストされています。

ドキュメントサイト用にNetlifyを設定するには、まずNetlifyアカウントにサインアップし、Railsアプリを含むGitHubリポジトリに接続します。

次の設定を使用します：

Repository
github.com/your-username/your-rails-repo
Base directory
docs
Build command
jekyll build
Publish directory
docs/\_site
Builds
Active

Netlifyサイトの作成時に一部の設定が利用できない場合は、[デプロイ]をクリックします 今のところ。その後、キャンセルして展開設定に戻ることができます 。ベースディレクトリをdocsに設定します NetlifyがRailsアプリではなくJekyllドキュメントサイトを確実にデプロイするようにします。

NetlifyがJekyllサイトのデプロイを完了したら、ライブサイトに移動して、すべてが正しく表示されることを確認します。

Netlifyを使用する利点の1つは、各プルリクエストから直接ライブプレビューリンクを提供することです。

次に、プルリクエストをマージしてサイトの再デプロイをトリガーする前に、変更が正しく公開されることを確認できます。次のセクションでは、このワークフローについて詳しく説明します。

GitHubでの編集ワークフローの設定

ドキュメントを作成するための戦略とそれを公開するサイトがあれば、ドキュメントを作成してソフトウェアワークフローに統合する準備が整います。

一般的な編集ワークフローには、ドキュメントのドラフト、ドキュメントのレビュー、公開が含まれます。ライターは自分の仕事の独自のレビューを実行する必要がありますが、編集者、マネージャー、および利害関係者は、多くの場合、最終的なレビュープロセスの一部です。これはソフトウェア開発プロセスに似ているため、ソフトウェア開発ツールを使用してプロセスをより効率的にすることができます。

GitHubを使用するチームの編集ワークフローの例を次に示します。

1. [ライター]ドキュメント機能のリクエストまたはバグに応じてファイルを作成または更新します（GitHubの問題に記載されています）。
2. [ライター]変更をGitHubブランチにプッシュします。
3. [ライター]プルリクエストを開きます。
4. [レビュー担当者]変更を確認します。
5. [Reviewer / Maintainer]変更をリポジトリにマージします。これにより、ドキュメントサイトの新しいビルドがトリガーされます。

GitHubは、コンテンツの変更履歴を自動的に管理します。これは、docs-as-codeワークフローでも重要です。何が変更されたか、誰が変更したか、いつ変更されたか、および変更された理由または方法（コメント、ディスカッション、または関連する問題で言及されている場合）を確認できます。これは、チームのすべてのメンバーがいつでも見ることができるように1か所に保存されます。

---
layout: default
title: Blog Posts
nav_order: 1
---

## Creating a Blog Post

...

git checkout -b docs/blog-posts
git add docs/blog_posts.md
git commit -m "Create doc: Blog Posts"
git push -u origin docs/blog-posts