AsciiDocの文書をCodePipeline/CodeBuildでHTMLに変換してみた | DevelopersIO
こんにちは、かたいなかです。 今回はGitHubにpushしたAsciiDocの文書をCodePipeline/CodeBuildでをHTMLに自動で変換する方法をご紹介します。 AsciiDocとは AsciiDocはドキュメントや記事、スライドショーなどを記述するためのテキストドキュメントのフォーマットです。AsciiDocのファイルはHTMLやPDF、EPUBなど様々な形式へ変換することができます。 Markdownよりも表現力が高いのも特徴で快適にドキュメントを作成することができます。 また、AsciiDocではPlantUMLなどを文書内に埋め込むことができ、UMLを多用した視覚的にわかりやすいドキュメントを容易に作成できます。 なぜHTMLに変換するのか GitHub上ではそのままでもAsciiDocの形式のファイルをある程度きちんと表示してくれます。しかし、PlantUMLで
Read the Docs(Sphinx)でオープンソースのドキュメントをいい感じに書いてみる
B! 139 0 0 0 最近良くGitHubなんかで公開されてるオープンソースのドキュメントを見ようとすると こんな感じの似たようなフォーマットで書かれているものが多くなっています。 余りに多いので最初GitHubのサービスかな、とか思ったんですが、 これはまた別のRead the Docsという ドキュメント用ホスティングサービスによるものでした。 Read the Docs Read the Docsでドキュメントを公開してみる Sphinxのインストール レポジトリ側の準備 Read the Docsへの登録 ページを作成 Indexページ ページ内容の編集(Markdown to reStructuredText) タイトル ハイパーリンク 画像 リンク付き画像 インラインマークアップ コードブロック リスト テーブル Pythonのモジュール説明 その他reStructured
WebAPIリクエスト仕様書としてcurlコマンドのご提案 - Qiita
WebAPIの仕様を記述する方法はいくつかあると思う。 普通に日本語で記述する JSON Hyper-Schema、WADL、RAML、Swaggerなどを使う 仕様書の代わりにプログラムを書く HTTPメッセージそのものを記述しておく でも、文法にばらつきがあったり、読みにくかったり、ツールのセットアップが面倒だったり、どれもイマイチな所があって、手軽な方法が欲しいと思っていた。 何気なくcurlコマンドのオプションを調べていたら、「もうこれでAPIドキュメント扱いにしちゃえばいいんじゃね？」と思えてきたのでメモしておく。 curlコマンドのおさらい curlコマンドはlibcurlの付属コマンドで、最近のUnix系OSなら大抵最初から入っていると思う。コマンドの詳細はmanを読んでいただければ。 cURL - How To Use （マニュアルページ日本語訳） curlコマンドのオプシ
ドキュメントを書く技術 - blog
READMEを始め、ソフトウェアのドキュメント全般を書く技術というものをもっと洗練させていきたい。要件定義書のようなものだけでなく、開発方針や設計方針、API定義などなど。 これらのドキュメントをしっかりと整備するだけで、レビューの質も上がり新しい人が入ったときもスムーズに意識のズレなく開発ができる。はずだが、なかなかドキュメントの上手い書き方や管理の仕方というものは、コーディングのそれとは違い議論が活発ではない。 最近試してみたこと そういったドキュメントの中でも、"開発方針"や"設計思想"をどう残していくかということを考えている。それらを残しておくことで、コーディングのときも立ち戻る場所ができ、大きく道を踏み外さなくなる。 例えば、レイヤードアーキテクチャのようなものの"境界"をドキュメントにしていく。MVCでもクリーンアーキテクチャでも何でも良いけど、それらのアーキテクチャではそれぞ
コードに仕様書パスをコメントで書くのやめようよ - Qiita
（まず追記） 自分たちで新たに作成する仕様書はMarkdownで記述してGitHubで管理しています。 こんなのも書いたくらいだし、そこは犯していないです。GitHubを中心とした開発プロセス ドキュメント管理 この記事内で言う仕様書とは、「エクセルで作られて共有サーバに置いてあるチーム管理外のファイル」を指します。 こーゆーの、良くあるよね？ public class FooService { /** * 仕様書：ad.xxx.net/development/lorem/ipsum/dolor/sit/amet/consectetur/adipiscing/elit/sed/do/eiusmod/tempor * incididunt_2.xlsx */ public void apply() { } } 見た瞬間「_2.xlsxってなんだよォ...このパス絶対古いんじゃあねェのー？」っ
ブロック図生成ツール blockdiag — blockdiag 1.0 ドキュメント
ブロック図生成ツール blockdiag¶ blockdiag シリーズはシンプルなテキストからブロック図などの画像を生成する画像生成ツール群です。 blockdiag を用いると以下のような図が簡単に生成できます。 blockdiag の主な機能: 数種類の図に対応 ブロック図 (blockdiag コマンド) シーケンス図 (seqdiag コマンド) アクティビティ図 (actdiag コマンド) 論理ネットワーク図 (nwdiag コマンド) テキストベースの定義ファイルから画像ファイルを生成 (graphviz 風の文法を採用) 定義にあわせて図の配置を自動的に決定 (自動レイアウト) Sphinx, Trac, Redmine, 各種 Wiki エンジン等、多様なシステムへの画像埋め込みに対応 Enjoy documentation with blockdiag !
ドキュメント書くのを限界までラクにする - Qiita
はじめに はじめまして。CYBIRDエンジニア Advent Calendar 23日目の@umiyoshです。 なんだかここ最近Jenkinsばかり触ってます。先週インフルエンザにかかったのですが、高熱の夢の中で永遠とJenkinsとふれあってました。寝ても覚めてもJenkinsです。 22日目は@takashi_hondaさんのプログラミングがはかどる音楽TOP10でした。 音楽とプログラミングって相性良いですよね。私もお勧めリストのDaft Punk聞きながら作業はじめました。SoundCloudにDaft punk公式アカウントがうｐしてて驚いたし、いい曲ではかどります。そしていまはおニャン子クラブのremixみたいのを聞いてます。SoundCloudは摩訶不思議です。 本日の内容 本日の内容ですが、やはりJenkinsです。寝ても覚めてもJenkinsですよね。 長いこと仕事をし
1
リリース、障害情報などのサービスのお知らせ
最新の人気エントリーの配信
j次のブックマーク
k前のブックマーク
lあとで読む
eコメント一覧を開く
oページを開く
Amazon.co.jp: [改訂第2版] [入門+実践]要求を仕様化する技術・表現する技術 -仕様が書けていますか?: 清水吉男: 本![Amazon.co.jp: [改訂第2版] [入門+実践]要求を仕様化する技術・表現する技術 -仕様が書けていますか?: 清水吉男: 本](https://cdn-ak-scissors.b.st-hatena.com/image/square/455db559d48a4549f2430c1467d65d680b64c311/height=288;version=1;width=512/https%3A%2F%2Fm.media-amazon.com%2Fimages%2FI%2F51hV6os4M5L._SL500_.jpg)