サクサク読めて、アプリ限定の機能も多数！
トップへ戻る
アメリカ大統領選
sphinx-users.jp
警告 この記事は古い為 easy_install の使用等、現在では非推奨の説明があります。インストール周りについては Windowsへのインストールの手順を参照してください。 これまでの説明で紹介してきたテンプレートは、あなたのソフトウェアのドキュメント作成に使用することができる基盤となります。ここからは、Pasterを使用して、自分自身のドキュメントのポートフォリオを構築するために、それ以外のテンプレートを追加するための方法を紹介していきます。 プロジェクト中に作成するドキュメントの量に関しては、必要最低限で、十分というのを心がけてください。追加されるそれぞれのドキュメントについても、対象となる読者を明確に定義し、実際のニーズを満たすようにします。実際に価値の増加に寄与しないドキュメントは書くべきではありません。 ドキュメントのランドスケープの構築¶ 前節で説明をしてきたドキュメントポ
GitHub Actionsを用いてGitHub Pagesへのデプロイを自動化する¶ 日時: 2020/01/18 作者: 辻大志郎 概要¶ GitHub Actions を用いて HTML ファイルの生成とデプロイを自動化します。ドキュメントのホスティング方法はいくつかありますが、ここでは GitHub Pages を用います。 master ブランチの /docs に公開するファイルを格納し、公開するようにします。 gh-pages ブランチにデプロイして公開する方法もありますが、今回は割愛します。 GitHub Pages を使ったホスティング方法は Github Pagesを使ってドキュメントを公開 もご覧ください。 リポジトリのディレクトリ構成¶ 下記のディレクトリ構成を想定します。 . ├── .github/workflows/main.yml // GitHub Acti
html5j 電子出版部勉強会「JLREQとCSS」参加レポート¶ 日時: 2017/03/14 19:30〜 場所: 日本マイクロソフト株式会社 イベント告知: http://kokucheese.com/event/index/456623/ 参加した人: 渋川よしき Sphinxのアウトプットを魅力的にするためにも仲良くしたいCSS3の最新動向を聞きにきました。 今日はこの頃あと19:30から、html5j電子出版部の勉強会『JLREQとCSS』です。 #html5jpub pic.twitter.com/j03uB7AVrm — Saki(さっくる) (@sakkuru) March 14, 2017 まとめ¶ 初めての参加で、客席？側の方の名前とか分からずすみません。 ドキュメントツールのSphinxのepub改善という立場でまとめると「改行してもいいよ」「ページを分けてもいいよ
インラインマークアップ前後にスペースを入れたくない¶ Sphinxが使っているreSturucturedTextでは、インラインマークアップの前後にスペースが必要でした。スペースなしでは単語の区切りを認識しないため、インラインマークアップが無視されます。
buildout を利用して Sphinx 環境を構築する¶ 複数人で Sphinx 文章を扱う場合、ネックになりがちなのが各々のマシンに Sphinx をインストールすることです。特に、Sphinx に加えて外部の Sphinx 拡張を利用している場合は混乱が生じがちです。 ここでは開発環境構築ツールである buildout を利用して、Sphinx 環境の構築を行います。 buildout の導入¶ buildout は以下の 2つのファイルで構成されます。 bootstrap.pybuildout の実行環境を構築するスクリプトです。各マシン上で最初に 1度だけ実行します。 Web 上に公開されているものを wget コマンドで取得します: buildout.cfg環境定義のための設定ファイルです。インストールするパッケージなどを記述することができます。 vi などのテキストエディタ
conf.pyにiniファイルから設定を読み込む¶ Sphinxの設定をconf.pyの外に書いておきたい場合があります。例えばiniやyamlに定義した値を読み込みたい場合はconf.pyに以下のように記載します。 conf.py¶ Sphinxはconf.pyを読み込むときに以下の順番で処理します。 conf.pyをexecfile()相当の処理でSphinx内にロードする ロードした設定値をSphinx内のapp.config._raw_configに保存する conf.pyにsetup()があればこの関数を呼び出す app.config._raw_configからapp.configに値を移す 以下に2つの方法を紹介しますが、それぞれ処理のタイミングが異なります。 方法1¶ conf.pyの読み込み時に値を設定する方法です。(前述の処理1) conf.py: #... #...既存
取り消し線を引きたい¶ Sphinxには取り消し線(sタグ)をマークアップする記法がありません。 取り消し線を使う場合には、新しくロールを定義し、それをクラス名としたスタイルシートを用意します。 追加するロール:
htmlを直接書きたい¶ rawディレクティブを使うと、HTMLを直接記述できます。 ここでは一例としてcheckboxを使ってみます。
ドキュメントを部分的に公開/非公開にしてビルドする¶ 日時: 2012/11/24 作者: 東健太 複数の人/会社が見るドキュメントを書く場合、特定の人には見せてはいけない情報や、逆に特定の会社にだけ見せたい情報が含まれることがあります。 こんなときは、ドキュメントの各部分について公開/非公開を変えつつビルドすることができると非常に便利です。 ここでは、タグを使ってドキュメントの構成を調整するためのテクニックを紹介します。 テクニック¶ タグをつけてビルドする¶ ビルドコマンドにタグを渡すことで、ドキュメント内でタグを参照して処理を切り替えることができます。 $ sphinx-build -b html -t tag1 -t tag2 source_dir dest_dir もしくは $ make SPHINXOPTS='-t tag1 -t tag2' html
Sphinxの過去と、未来¶ 著者: Georg Brandl 日付: 2012/12/25 原文: Sphinx, past and future 翻訳: @r_rudi, @shimizukawa このエントリーは日本語の Sphinx Advent Calendar 2012 に参加してくれないかというリクエストに応えて書いています。彼らはすごいよ！彼らは今年Sphinx Conferenceを開催して、イベントには70人もの人たちが集まったんだ！ Sphinx はいまや5歳になってるし、たぶん今までの歴史を振り返り、将来を語るのに良い時期じゃないかな。 このプロジェクトは2007年前半のいつ頃かに始まった。この投稿は私がPythonメーリングリストで見つけた中で一番古い。この時、Pythonのドキュメント作成のためのソースはLaTeXで書かれていた。私は科学的な文章を書くときには絶
不自然な空白が表示される¶ 日本語文章を書いているとHTMLで出力した際に不自然な空白が文章中のところどころに出力される場合があります。これは、段落中で改行するとその改行が空白文字として出力されてしまうからです。 この問題を解決するには日本語拡張を使います。 ここから japanesesupport.py をダウンロードします。 ダウンロードした japanesesupport.py を conf.py を置いてある場所に移動させます。(sourceとbuildを分割している場合はsourceの下、していない場合はMakefileと同じ場所) conf.py を以下のように書き換えます。 sys.path.insert(0, os.path.abspath('.')) # コメントを外します extensions = ['japanesesupport', 'その他の拡張'] # 加えます
ミッションステートメント¶ アート・オブ・コミュニティ(オライリー・ジャパン刊行)の2章のテンプレートを通じて作り上げた、コミュニティの核となる考えをまとめたものになります。2011/7/23のイベントを通じて作成されたものです。 2.2.3 読み手 vs 書き手¶ Sphinx-users.jpは読み手のコミュニティー。Sphinx開発を中心としたコミュニティーではありません。利用者の視点に立って、利用者に向けての情報を提供することが目的です。ただし、開発に関連した情報を提供しない、というわけではありませんが。比重が読み手寄りです。 今後、開発向け情報を提供していくときには、開発向けページを用意して、利用者向けとは明確にパーティショニングして提供していきたいと考えています。 2.3 コミュニティーのデザイン¶ ミッションは何か？ Sphinxを活用して、ドキュメント作成をパワーアップした
PyCon JP 2012 全体のタイムテーブルについてはプログラム - PyCon JP 2012 を参照して下さい。 セッション詳細¶ Sphinx ではじめるドキュメント生活 2012¶ すぐれたドキュメントツールである Sphinx を使って、あなたのドキュメントを書いてみませんか。 Sphinx は多くの OSS のマニュアル、リファレンスで採用されている他、 IT企業でも利用されはじめています。ドキュメントを作りたくなってしまうとまで言われる Sphinx の魅力を皆さんにご紹介します。 言語: 日本語 日時: Sep 16 15:15-15:40 場所: Room 452 Takeshi Komiya (株)タイムインターメディア所属 blockdiag、Sphinx などといったドキュメンテーションツールに興味を持ち、ツール、拡張モジュールの開発やコミュニティ活動を行なって
注釈 Sphinx-1.8 以前は setup() 関数を定義し、その中で add_stylesheet() を呼び出していましたが、現在では設定項目 html_css_files を使って設定します。 https://www.sphinx-doc.org/ja/master/usage/configuration.html#confval-html_css_files これでcustom.cssもHTMLから読み込まれるようになります。 同様に app_add_javascript('custom.js') を使えばJSファイルも追加できます。 Sphinx標準テーマであれば、add_stylesheetやadd_javascriptを使ってcssやjsを追加することが出来ます。
中間ファイル *.doctree の内容をみてSphinxがどのようにreSTをparseしているか知りたい¶ SphinxはreSTフォーマットで書かれたドキュメントを中間形式に変換してから、出力形式に書き出します。例えば make html を行うと以下の順番に処理が行われます。 make html を実行する conf.py等の環境情報を _build/doctree/environment.pickle に出力する 各 *.rst の内容を _build/doctree/*.doctree に出力する environment.pickle と *.doctree を元に _build/doctree/*.html を生成する ここで出力されたdoctreeファイルに、ドキュメントの中間形式 = Sphinxのドキュメントツリー情報が格納されています。これを見ると、reStrucut
さくらインターネットで自動ビルド¶ 日時: 2012/1/25 作者: 渋川よしき Sphinx-Users.jpで2008年ぐらいから使っている方法を紹介します。常駐のできない、一番安価なさくらのスタンダードプランとBitbucketを使う方法です。 この方法には以下のようなメリットがあります。 サーバのパスワードを公開することなく、複数人でコンテンツの管理を行うことができる BitbucketのウェブUIを使って、権限設定などを簡単に行うことができる ウェブのコンテンツをすべてバージョン管理で制御できる 自前のテンプレートや特別な拡張機能がいくらでも使える 問題の報告や管理に、Bitbucketのチケットのシステムが利用できる パッチの受け取りに、pull-requestを使うこともできる リポジトリの準備¶ http://bitbucket.org のサイトにアクセスし、リポジトリを
コードブロック内で特定の行だけ強調表示したい¶ Sphinx 1.1から導入された emphasize-lines を使います。 .. code-block:: python :emphasize-lines: 3,5 def some_function(): interesting = False print 'この行はハイライトされます' print 'この行はされません' print '...でも、この行はされます'
Sphinx-Users.jp © Copyright 2010-2020, Sphinx-Users.jp. Created using Sphinx 8.0.2. Last updated on 8月 18, 2024. Source repository.
ドキュメントのパワーアップ¶ Sphinxには様々なマークアップがあります。これを利用すると、見やすく情報量の豊富なドキュメントを作ることができます。 インラインマークアップ¶ 太字、斜体、リテラルなどが利用できます。
参加するには？¶ #sphinxjpではメーリングリストへの参加＝コミュニティへの参加とみなします。入会金や会費などは一切かかりません。 参加に際しては sphinx-users.jp 会則を確認して下さい。 必要なスキルは？¶ よく誤解される内容として「SphinxはPython(パイソン)というプログラミング言語で書かれているから、Pythonを知らないと使いこなせない」というものがあります。 Sphinxは確かにPythonで書かれていますが、Sphinxの拡張機能を作ったり、Sphinx本体のバグ修正や機能拡張をしたいと思わない限りは不要です。下記に、コミュニティで活動したい内容ごとの必要なスキルをまとめます。 ここで挙げた各種知識や能力などは一つの目安です。コミュニティでの活動を通じて、これから学ぶことも可能ですが、熱意と勇気は事前にご用意いただく必要があります。 何がしたいか？
警告 この記事は古い為 easy_install の使用等、現在では非推奨の説明があります。インストール周りについては Windowsへのインストールの手順を参照してください。 reStructuredTextはreSTとも呼ばれます。 (http://docutils.sourceforge.net/rst.html (英語) を参照してください。) reSTは、プレーンテキストを使ったマークアップ言語で、パッケージのドキュメントを作成する際に、Pythonのコミュニティ内で広く使用されています。reSTの優れている点は、ソースのテキストの状態でもそのまま読むことができるという点です。LaTeXのように、マークアップの文法のせいで読みにくくなるということはありません。 以下のテキストは、reST形式のドキュメントのサンプルです。 ======== タイトル ======== セクション
ダウンロード このドキュメントはバージョン1.1 (hg)のためのものです。まだリリースされていません。 Mercurialリポジトリのコードを利用するか、Python Package Indexにあるリリースバージョンを探してください。 疑問? 意見? Googleグループへの参加: もしくは、FreeNodeの#pocooチャンネルへどうぞ 何か気づいたことがあれば、issue trackerを使用して通知することもできます。 Sphinxは知的で美しいドキュメントを簡単に作れるようにするツールです。Georg Brandlによって開発され、BSDライセンスのもとで公開されています。 このツールはもともと、新しいPythonのドキュメントの変換のために作られました。Pythonのプロジェクトのためのすばらしい機能を提供してきましたが、現在ではC/C++も既にサポートしています。また、他
Sphinx-users.jp Ｘアート・オブ・コミュニティー (2011/7/23)¶ Sphinx-users.jpサイトを改善セヨ 日時: 2011/7/23(土) 13:00～18:00 場所: DeNA (新宿) 募集: http://atnd.org/events/17992 (終了しました) 2章を読みます。書籍にある内容をSphinx-users.jpに適用して読み解いていった内容を以下にメモとして残しています。 会の内容¶ コミュニティーの定義¶ なにかの成果を達成することを目的とした集団。Sphinx-users.jpは利用者向けの情報提供を目的としている。 2.2.3 読み手 vs 書き手¶ ここでいう読み手、書き手、はアート・オブ・コミュニティーに書かれている用語で、「コミュニティーが対象とするものを作る人向けの情報」を書き手向け、「ものを利用する人向けの情報」を読
ドキュメントの構築¶ ドキュメントのヘルパーとガイドラインを提供すると、読者と作成者の両方の仕事を簡単に改善することができます。そのために、前節で学んできたことを活用していきます。 ドキュメント作成者の視点から考えると、ガイドと一緒に再利用可能なテンプレート集が提供され、それをプロジェクトの中でいつどのように使用するかという説明があると、この目標は達成できます。これをドキュメントポートフォリオと呼びます。 ドキュメント読者の視点から考えると、どのようなドキュメントが提供されるのかという展望が提供されると、楽にドキュメントを読むことができるようになりますし、必要なドキュメントを効率良く探して利用できるようになります。 ポートフォリオの構築¶ ソフトウェア開発のプロジェクトの中で作られるドキュメントには、ソースコードを直接参照するような低レベルなドキュメントから、アプリケーションの概要を伝える
次のページ
このページを最初にブックマークしてみませんか？
『Sphinx-Users.jp :: ドキュメンテーションツール スフィンクス Sphinx-users.jp』の新着エントリーを見る
j次のブックマーク
k前のブックマーク
lあとで読む
eコメント一覧を開く
oページを開く
