Please don't write your documentation in Markdown
March 23, 2020 Please don't write your documentation in Markdown Please don't write your documentation in Markdown. Please. I'm begging you. Markdown is tolerable for short documentation, like a readme.md. Past that, it's the wrong tool for the job. Markdown is about formatting, not information Markdown is just a way to write simpler, nice looking HTML. There is direct mapping between _foo_ and <e
ふだん Markdown を書く技術者のための reStructuredText 文法まとめ
ふだんは Markdown を書いていて、稀に reStructuredText を書く必要がある技術者（私です）のための reStructuredText 文法まとめです。 reStructuredText のすべてを網羅するのではなく、あくまで「 Markdown にある機能を reStructuredText で使いたい」という状況を想定した上での簡易的なまとめです。 reStructuredText の詳細を本格的に学びたい場合は次の 2 つのページを参照することをおすすめします。 reStructuredText Primer — Sphinx documentation reStructuredText 「 Markdown なら書き方がわかっているんだけど、 reStructuredText でどう書けばいいかわからないので、いちいち検索してしまう」という方のお役に立てば幸い
Sphinx から完全に reStructuredText を追い出した話 - Hack like a rolling stone
いくつかの記事で紹介されているとおり、 recommonmark を使うと Sphinx で markdown を使うことができます。 Software Design 2016年4月号 Markdownで始めるSphinx MarkdownでSphinxできるようになったので試してみた（前編） - 意識の高いLISPマシン Markdownで書けるSphinxの構築 - Qiita しかし、recommonmark を利用しても、ドキュメント構造(toctree)を記述するためには部分的に reStructredText を使う必要がありました。 .. toctree chapter1 chapter2 chapter3 これは、文法を拡張する仕組みを持たない markdown の (commonmark の)構造上、仕方がないのですが、せっかく markdown でドキュメントを書いてい
reStructuredText vs Markdown for documentation
In this post I am going to share my experience of using Markdown and reStructuredText (RST) for technical documentation. As a library developer I have to write a fair amount of it, for example, the fmt library documentation, and I’ve used both languages extensively. In fact, I’m writing this blog post in Markdown. At first sight RST and Markdown look very similar. Both are lightweight markup langu
GoのreStructuredTextパーサgorstをリリースしました | hexacosa.net
タイトルどおりですが、GoのreStreucturedText実装を作ってみました。 https://github.com/hhatto/gorst 以前 GoでMarkdown live previewerのftcatってのを作った のですが、 リリースしたあとくらいに reStructuredText でも使いたいよなーって思ってました。 よしGoのreSTパーサ作ろうと思って 10月下旬にGitHubに空のリポジトリだけ作って 、 どこから手をつけたらいいのやらってグダグダ考えてほったらかしになっていたのですが、 2月に入ってちびちびと余暇の時間を使って進めて、やっと公開できるレベルになって公開したのが先日2/18でした。 使い方 現在はreSTからHTMLへの変換のみ対応しています。 現状はHTML以外のフォーマットに対応させる予定はありません。 $ go get github.c
Swift Documentation
Written by Nate Cook & Mattt July 11th, 2018 (revised) This article has been translated into: 中文 Code structure and organization is a matter of pride for developers. Clear and consistent code signifies clear and consistent thought. Even though the compiler lacks a discerning palate when it comes to naming, whitespace, or documentation, it makes all the difference for human collaborators. This week
多様なフォーマットに対応！ドキュメント変換ツールPandocを知ろう - Qiita
追記（2020.4.19） Pandoc User’s Guideを日本語に全訳しました。 よろしければご参照ください。 新しい翻訳をプレリリースしました！（翻訳途中の部分もあります） Pandocユーザーズガイド 日本語版 [2.7.2] — 日本Pandocユーザ会 2019.02.21 ドキュメント 旧日本語版：Pandoc ユーザーズガイド 日本語版 はじめに 今回は、ドキュメント作成Tips Advent Calendar 2012の1日目 （マインドマップから全てを紡ぎ出す - XMind+Pandocのドキュメント作成術 -） で少し紹介したPandocというツールについて、もう少し深く掘り下げて紹介したいと思います。 MarkdownとかreStructuredTextとか、流行ってますよね いわゆる軽量マークアップ言語が最近流行しています。特にMarkdownは猫も杓子も
Geanyが超うれしい件
2012/01/25 01:37 ※ 商品のリンクをクリックして何かを購入すると私に少額の報酬が入ることがあります【広告表示】 わけあって、VirtualBox上のubuntuでいろいろ書かなければいけない事態になっているわけですが、 OSXではいつもTextmateを使っていて、みんな大好きなvimとかemacsはどうも馴染まないのです。 reStructuredText Python使いの端くれなので、普段文章を書くときはいつもreStructuredTextで書いています。 最近はSphinxのおかげでPython使いにとどまらず OSSプログラマにも必須になりつつあるあのreStructuredText です。 構造を持っている reStructuredTextの何が良いって、htmlにできたりpdfにできたり、もちろんSphinxを使えることもなんですが、なにより 構造を持ってい
mooをフォークしてmeowをリリースしました | hexacosa.net
以前紹介した markdownファイルをリアルタイムプレビューできるツール moo 。 現在はJavaScriptをベースにしたツールに変わってしまったため、 reStructuredTextファイルも変換できるようにしたPython版をフォークして meow としてリリースしました。 mooの作者とのやり取りは このあたり 。 Python3でも動作します。 コードはGitHubにあげています 。 インストールと使い方 インストール $ pip install meow 起動。 $ meow REST.rst Preview on http://127.0.0.1:7777 Hit Ctrl-C to quit. 2013-06-22 00:37:21 INFO detected file change Ctrl+Cで停止します。 一度使ってみてください。では。
reStructuredText を Marked.app でプレビュー表示するメモ - 牌語備忘録 -pygo
修正2014-08-03：Path (MacOSX10.9) Connecting to the Mac App Store rst2html-2.7.py をインストール sudo port install py27-docutils Marked の設定 Prefarence -> Behavior Custom Processor の Custom Markdown Processor にチェック入れて Path を /opt/local/Library/Frameworks/Python.framework/Versions/2.7/bin/rst2html.pyそんで hoge.rst とか読み込むと表示される。 追記：エディタ指定 Prefarence -> Window Edit with のところで Emacs.app とかエディタを指定すると、Marked.app から
rst2pdfをWindowsで使ってみた - 偏った言語信者の垂れ流し
reStructuredTextからPDFを作成するrst2pdfというツールがあります。 インストール インストールはWindowsだと依存モジュールがCで書かれていて少し面倒になりますが、MacやLinux環境だとeasy_install一発で入ると思います。 特徴としては、 Pythonのモジュールだけで構成されていて、特別なツールが必要ない 日本語でも使える フォントの埋め込みができる 設定がjson Windows/MacOSX/Linuxどれでも使える あたりでしょうか。日本語対応してて、フォントの埋め込みができるのは大きいです。 依存モジュールは、以下の通り。Python2.5で試しました。 docutils PIL pygments simplejson reportlab PIL、reportlabはWindows用のインストーラでインストールするとよいです。simple
reStructuredText tool support
Salvaging (and extending) the list from an old version of the Wikipedia page: Documentation Primer Cheat Sheet Quick Reference reStructuredText and Sphinx Reference Implementations Although the reference implementation of reStructuredText is written in Python, there are reStructuredText parsers in other languages too. Python - Docutils The main distribution of reStructuredText is the Python Docuti
[翻訳] reStructuredText ディレクティブ
著者: David Goodger 問い合わせ: goodger@python.org リビジョン: $Revision: 3340 $ 更新日時: $Date: 2005-05-14 18:14:44 +0200 (Sat, 14 May 2005) $ 著作権: This document has been placed in the public domain. 翻訳者: 清水川 貴之 shimizukawa at gmail.com 原文: http://docutils.sourceforge.net/docs/ref/rst/directives.html このドキュメントはreStructuredTextの文書解析器で実装されているディレクティブについて記述されています。 ディレクティブは以下の構文にで記述されます: +-------+--------------------
ReStructuredText 文法まとめ - secretbase.log
Sphinxで使う軽量マークアップ言語 ReStructuredText で役立ちそうなサイトをまとめてみました。(ReStructedText基礎文法最速マスターがありそうで無かった) 文法 サイト名 説明 ReStructuredText 入門 ReStructuredText Primerの日本語訳 はやわかり reStructuredText プレーンテキストと変換結果の例がわかりやすい reStructuredText Markup Specification rstの詳細な仕様。チュートリアルや入門ではない reStructuredText入門 :: ドキュメンテーションツール スフィンクス Sphinx-users.jp よく使う記法。入門 Tips サイト名 説明 reSTおよびSphinxで文章を書く際のtips - そこはかとなく書くよ。 論文っぽい文章を書くときのti
DjangoでreStructuredText - PYTHONIC BOOM BOOM HEAD
探し方が悪かったのか、見つけるのに手間取った。でもその割に設定はすごく簡単だったというオチ。まあそもそも素のdjangoで出来るという考えが全くなかったのがいけない。 まず、docutilsがインストールされてないと元も子もないので、無ければインストールする。 $ pip install docutils続いて、settings.pyのINSTALLED_APPSにdjango.contrib.markupを追加する。 INSTALLED_APPS = ( 'django.contrib.auth', 'django.contrib.contenttypes', ... 'django.contrib.markup', # これ追加 ... ) あとはテンプレート中に {% load markup %} を追加して、ReSTなテキストに対して restructuredtext というテンプ
ReStructuredText 入門
以下の文章中に "(quickref)" という形式のリンクがあります。これは、 Quick reStructuredText ユーザリファレンスへの相対リンクです。このリンクが 切れている場合は、 オンラインのクイックリファレンス を参照してください。 構造 まずはじめに、"Structured Text" （構造化されたテキスト）という呼び方には、 いくぶん不適切なところがあると指摘しておきます。実際には、首尾一貫したパターンを使う "Relaxed Text" （形式ばらないテキスト）とでも呼ぶべきものです。そのパターンを HTML コンバータで変換することで、WEB ブラウザで扱えるような「非常に構造化された テキスト」が生成されるのです。 最も分かり易くて基本的なパターンは、 パラグラフ（段落） (quickref) です。 （1つ以上の）空行で区分されたテキストのひとかたまりが
リリース、障害情報などのサービスのお知らせ
最新の人気エントリーの配信
j次のブックマーク
k前のブックマーク
lあとで読む
eコメント一覧を開く
oページを開く
GitHub - hhatto/gorst: Go implementation of reStructuredText
restructuredtext用のエディタを作ってみた - 偏った言語信者の垂れ流し
https://github.com/ralsina/rst-cheatsheet/blob/master/rst-cheatsheet.rst
Handy two-page restructedtext cheat sheet - Reinout van Rees