Pythonプログラミング入門 — Pythonプログラミング入門 documentation
Pythonプログラミング入門¶ ▲で始まる項目は授業では扱いません。興味にしたがって学習してください。 ノートブック全体に▲が付いているものもありますので注意してください。
Pythonプログラミング入門¶ ▲で始まる項目は授業では扱いません。興味にしたがって学習してください。 ノートブック全体に▲が付いているものもありますので注意してください。
ドキュメント駆動開発v2
前提 ここで言っているドキュメントは仕様書ではなく、顧客向け製品ドキュメント。 ミドルウェア製品を開発 小さなチーム パッケージ製品とパッケージ製品のクラウド版 そのため顧客に提供するドキュメントが必ず必要 GitHub を利用 自分で開発する場合のフロー 作りたい機能をぼんやりでいいので GitHub Issue に追加する feature ブランチを切る デザインドキュメントをリポジトリの doc/ 以下に書く デザインドキュメントに合わせてコーディングを進めてなんとなく動くところまで作る 動かなくてもいいのでイメージを膨らませるためにコードを書いてみる デザインドキュメントは書き捨て前提で、とにかくメモを書く 製品ドキュメントを書き始めて、一旦書き終える ブランチマージに向けてコーディングを進める 書ける範囲でテストを書く ドキュメントを平行して修正する プルリクエストをだしてレビュ
オンラインドキュメントと日本語全文検索
自社では Sphinx というドキュメントツールを利用しているのですが、残念ながらこれに付属している検索機能の日本語検索はかなり厳しいです。また残念ながら Sphinx 開発側も検索周りを改善するという予定は直近ではないようです。 そして検索というのはとても難しい技術なため自分のような素人では導入して「普通に期待する動作」をさせるまでの距離はとても遠いです。 ただ、なんとかして日本語全文検索を実現したいという思いはここ10 年くらいずっと思っていました。これは自社の Sphinx テーマを作ってくれている社員ともよく話をしていたのですが、どうしてもリソースをつぎ込めずにいました。 まとめ日本語検索に対応している Meilisearch を採用したドキュメントスクレイパーの実行は GItHub Actions (Self-hosted Runner) を採用した自社 Sphinx テーマの検
この記事の目的 最近「良いドキュメントが作れているな」と思う機会が増えてきたので、その知見をアウトプットしたくなった。 想定読者 今所属してる組織(会社/プロジェクトなど)のドキュメントがイマイチで悩んでいる人 そもそもドキュメントが無い組織に所属していてつらい思いをしている人 「ドキュメントを作れ」という漠然としたタスクを振られて困っている人 想定読者ではない人 メンテなブルなドキュメンテーションのエコシステムが完成している組織で更によいやり方を模索している人 私もまだ模索中なので、いいやり方があれば教えてほしいです👀 顧客提出などの「納品が必要」なドキュメントの管理方法を模索している人 この記事では「社内の情報共有」にスコープを切って話をしています 書いている人のスペック(参考) 歴５年くらいのなんちゃってフルスタックエンジニア 普段は Node.js / React.js or R
はじめに 「研究用のプログラムにもテストコードやドキュメント書いたほうがいいよね。」 「分かっちゃいるけど、そんな面倒なことやってられないよ。」 という研究者あるあるを解決すべく、僕が普段実践している開発スタイルを紹介します。 この開発スタイルのすごいところは： テストやドキュメントを一切書かない場合と比べて 追加の工数がほぼゼロ。 普通にコーディングしているだけで、いつのまにかテストコードとドキュメントまでできあがっている。 実装、コメント、テスト、ドキュメントが自然に同期するので、保守しやすい。 Pythonを例に紹介しますが、コメント内にテストを書けるツールと、コメントからドキュメントを生成できるツールをもつ言語ならばどれにでも応用できるはずです。 この開発スタイルに至った背景 ソフトウェア開発において、テストコードやドキュメントを整備することでプログラムの品質が向上することは広く知
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
「Jupyter Book」プロジェクトは8月13日、最新のJupiter Bookを発表した。ブック作成でJekyllに代わってSphinxを用いるようになるなど、多数の変更が加わっている。 Jupyter Bookは演算処理コンテンツを含む素材からWebサイトやドキュメンテーション、出版レベルの本を構築できるオープンソースのプロジェクト。Python向けのインタラクティブなノートブックとしての利用で知られており、インタラクティブかつ実行可能なドキュメント向けのオープンソースのツールを構築するExecutable Book Projectの支援を受けている。なお、プロジェクトはまだベータ段階にある。 最大の変更として、ブックの作成でこれまで使用していたJekyllに代わって、Sphinxドキュメンテーションエンジンを用いるようになった。また単一リポジトリから、複数のモジュラー ツール構成
Jupyter Book is an open source project for building beautiful, publication-quality books, websites, and documents from source material that contains computational content. With this post, we’re happy to announce that Jupyter Book has been re-written from the ground up, making it easier to install, faster to use, and able to create more complex publishing content in your books. It is now supported
追記GitHub Sponsors で組織がスポンサーになれるようになったため、個人アカウントから組織アカウントへ切り替えました。 月 500 ドルなぜスポンサーになったのか時雨堂では自社製品のすべてのウェブドキュメントに Sphinx を利用しています。そのため Sphinx を継続的な開発を少しでもやりやすくしてもらえるようにスポンサーになりました。 個人としても Sphinx は利用させてもらっており、今まで小宮氏への個人的なスポンサーにはなっていました。 ただ今後も Sphinx を自社製品のドキュメントとして使い続けたいという思いから、企業としてメインの開発者である小宮氏への継続的なスポンサーになるべきだと判断しました。 時雨堂がスポンサーになっている開発者Cowboy や Gun の開発者である Loïc Hoguin 氏Blend2D や AsmJit の開発者である Pet
［Python入門］クラスの継承
クラスの役割 本連載では以前に、関数は「何らかの定型処理を行うひとまとまりのコードを再利用する」ための仕組み、パッケージやモジュールは「複数の関数などを1つ以上のファイルにまとめることで、それらを他のコードから再利用する」ための仕組みといった話をしてきた。クラスもそうした「コードの再利用を可能にする」仕組みの一つだ。 クラスとは「何らかのデータ（インスタンス変数）と、それらを処理するためのコード（メソッド）をひとまとめにして名前を付けることで、後からそれらを再利用する」ための仕組みといえる。なお、モジュールやパッケージでクラスを定義すれば、それらももちろんインポートして利用できるようになる。 今述べたような「何らかのデータと、それらを処理するためのコード」を1つの単位（オブジェクト）として考え、「さまざまなオブジェクトを、メソッド呼び出しを通じて、どのように作用させていくかを記述することで
モチベーション ドキュメントツール Sphinx から出力した HTML オンラインドキュメントに日本語対応の全文検索機能を追加したい。 結果 オンラインドキュメントと日本語全文検索 前提 日本語全文検索に対応する OSS を利用する ドキュメントツールは Sphinx を利用する Sphinx の検索バーを置き換える サーバレスの検索は諦める サーバ運用を検討する 企業利用前提なので費用がかかっても良い 検索は難しいので検索部分は頑張らない 完璧は求めない reStructuredText を解析するのではなく HTML を解析して処理する Meilisearch を採用 いろいろ調べたりしていたが Meilisearch が良さそうと判断した。 Meilisearch 日本語検索に対応している Rust で書かれており性能がでそう Rust であれば問題が起きた際、会社でなんとかできる
Jupyter Notebook（ジュピター・ノートブック）とはJupyter Notebook（ジュピター・ノートブック）とは、ブラウザ上で動作するプログラムの対話型実行環境です。データ分析には欠かせないツールの１つです。 ノートブックと呼ばれるファイルにpythonなどのプログラムを記述し、実行結果を逐次確認しながら、データ分析を進めることができます。 Jupyter Notebook上では、様々なライブラリを使うことができ、TensorFlow（テンソルフロー）などの機械学習やディープラーニング用のライブラリも動作させることができます。 またJupyter Notebookでは、入力したプログラムの実行結果が、プログラムの直後に表示されるので、結果が分かりやすく、すぐに確認することができます。 このような3Dのグラフも表示することができ、複雑なデータ分析の結果もビジュアルで表現し、確
Sphinx makes it easy to create intelligent and beautiful documentation. Here are some of Sphinx’s major features: Output formats: HTML (including Windows HTML Help), LaTeX (for printable PDF versions), ePub, Texinfo, manual pages, plain text Extensive cross-references: semantic markup and automatic links for functions, classes, citations, glossary terms and similar pieces of information Hierarchic
ふだんは Markdown を書いていて、稀に reStructuredText を書く必要がある技術者（私です）のための reStructuredText 文法まとめです。 reStructuredText のすべてを網羅するのではなく、あくまで「 Markdown にある機能を reStructuredText で使いたい」という状況を想定した上での簡易的なまとめです。 reStructuredText の詳細を本格的に学びたい場合は次の 2 つのページを参照することをおすすめします。 reStructuredText Primer — Sphinx documentation reStructuredText 「 Markdown なら書き方がわかっているんだけど、 reStructuredText でどう書けばいいかわからないので、いちいち検索してしまう」という方のお役に立てば幸い
JAWS-UG CLI専門支部の手順書の設計思想と実装手法 /20201223-model-operation-procedure-jawsug-cli
「JAWS-UG CLI HUB #7R 手順書ないと」での発表資料です。 (運用設計ラボ合同会社 波田野裕一)
最近Sphinxつかってドキュメントを書いてるのですがなかなかイケています。 SphinxとはPython製ドキュメンテーションビルダーで、reStructuredTextという記法で書かれたテキストファイルをHTMLやPDFなどに変換することができます。 SphinxはPythonの公式ドキュメントなどにも使われており、見たことある方も多いのではないでしょうか。 今回は「Sphinxを自動デプロイ&公開する方法」を紹介したいと思います。 構成図 せっかちな人へ GitHubの方にソースコード全部あげています。 Sphinxのインストール 詳細は公式ドキュメントを確認ください。 pipenvを使ってライブラリをインストール pipenv install sphinx クイックスタート pipenv shell sphinx-quickstart 作成されたファイル $ tree -L 2
先ほど Sphinx-2.4.0 をリリースしました。 Sphinx は 2ヶ月ごとの定期リリースを目指しているので、大体予定通りのリリースです。 2.4.0 では autodoc まわりの機能が大きく改善されました。この記事ではその改善点についてまとめたいと思います。 変数アノテーションへの対応 autodoc: Support type annotations for variables #7051: autodoc: Support instance variables without defaults (PEP-526) これまで、コード内の変数アノテーションはドキュメント化されていなかったのですが、2.4 からはドキュメントに出力されるようになりました。 いまや型情報は規模の大きいプログラムを書くのに欠かせない情報となっています。型情報をアノテーションすることは、あなたと開発チー
アプトポッドにて、テクニカルライターとして製品マニュアルの制作を担当している篠崎です。 現在弊社では、製品マニュアルの制作に、Sphinxを導入しようとしています。Sphinxは、1つの原稿ファイルからHTML、PDF等を出力できるドキュメントジェネレーターです。この記事では、SphinxにLuaLaTeXを組み合わせて日本語PDFを生成する方法を探ってみました。 背景 SphinxでLuaLaTeXを使う設定 (A) LuaLaTeXを使用する (B) LaTeXドキュメントクラスとしてltjsbookを使用する (C) Polyglossiaパッケージを読み込まないようにする (D) サンセリフ系フォント、ゴシック系フォントを指定する（AXISフォントを使用するため） (E) デフォルトのフォントをサンセリフ系、ゴシック系に変更する（AXISフォントを使用するため） おわりに、今後に向
自分自身のポートフォリオを構築する
警告 この記事は古い為 easy_install の使用等、現在では非推奨の説明があります。インストール周りについては Windowsへのインストールの手順を参照してください。 これまでの説明で紹介してきたテンプレートは、あなたのソフトウェアのドキュメント作成に使用することができる基盤となります。ここからは、Pasterを使用して、自分自身のドキュメントのポートフォリオを構築するために、それ以外のテンプレートを追加するための方法を紹介していきます。 プロジェクト中に作成するドキュメントの量に関しては、必要最低限で、十分というのを心がけてください。追加されるそれぞれのドキュメントについても、対象となる読者を明確に定義し、実際のニーズを満たすようにします。実際に価値の増加に寄与しないドキュメントは書くべきではありません。 ドキュメントのランドスケープの構築¶ 前節で説明をしてきたドキュメントポ
PyCon JP 2020 で弊社メンバーが発表しました | Webシステム開発／教育ソリューションのタイムインターメディア
CTOの小宮です。 先月開催された PyCon JP 2020で「How Sphinx generates document from Python code」というテーマで発表してきました。 トークの内容はちょっと濃い目で、Sphinx の autodoc をテーマに Python コードの動的および静的なコード解析方法を解説するいうものでした。 普段から Python のコードを書いている方でも、この手のコード解析をする機会は少ないと思います。 自分も Sphinx のメンテナンスをするまでは inspect や ast 、tokenizeといったモジュールには触れる機会が殆どありませんでした。 しかし、開発の中で普段つかっている flake8 や black、mypy などの開発補助ツールはこうしたコード解析手法を組み合わせて実装されています。 普段の開発に役に立つわけではありません
Sphinx の使い方
Python 製ドキュメントツールである Sphinx の入門書です。 Windows 11 の操作練習を兼ねて評価版 Windows 11 上に環境を構築しました。Windows 10 上でも同じ手順で対応できると思います。 最初に Sphinx で文書を作成し、 GitHub Pages で公開するまでの手順を説明します。その後、Sphinx の各機能を説明します。 本書が Sphinx の使用をご検討されてている方が一歩踏み出す一助になれば幸いです。
TERASOLUNA Server Framework for Java (5.x) Development Guideline — TERASOLUNA Server Framework for Java (5.x) Development Guideline 5.6.1.RELEASE documentation
TERASOLUNA Server Framework for Java (5.x) Development Guideline¶
New features of autodoc in Sphinx-2.4 - Hack like a rolling stone
Today, I released Sphinx-2.4.0, now available on the Python package index at https://pypi.org/project/Sphinx/. It includes 18 new features and 23 bugfixes. For the full changelog, go to http://www.sphinx-doc.org/en/master/changes.html. In this article, I'd like to introduce you to new features of autodoc. Support type annotations for variables Until now, autodoc did not document type annotations f
HonKit 公式ドキュメント HonKit 製作者によると GitBook -> HonKit への移行の経緯は以下の通りです。 GitBookはMarkdownからドキュメントページや書籍を作成するツールですが、 以前OSSで公開されていたGitBook(legacy)はDeprecatedとなって開発は止まっています。 ⚠️ Deprecation warning: As the efforts of the GitBook team are focused on the GitBook.com platform, the CLI is no longer under active development. All content supported by the CLI are mostly supported by our GitBook.com / GitHub integra
また、これを拡張機能を使って実現できるジェネレータは個人的には今現在避けています。 デフォルトで動くってやはり素晴らしいです。 環境構築サイトのジェネレータが依存しているパッケージやモジュールが、 自分にとって不親切なもの、わかりにくいものは避けましょう。 本来の目的は文章を書くことです。 ジェネレータの依存関係を解決することではありません。 また、OSSなどでドキュメントを他の人が書き換える場合がある場合、メンテナスしやすいようにコマンド1つで立ち上がるようにしておくべきです。 Cirlcle CIのドキュメント(circleci/circleci-docs)を修正したときはちょっと感動しました。なぜならば、docker-compose upのみで自分の環境に出来上がったからです。 とても小さな修正でしたが、このお陰でスムーズにコントリビュートでき、とても印象的だったのを覚えています。
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
j次のブックマーク
k前のブックマーク
lあとで読む
eコメント一覧を開く
oページを開く
【汎用ソフトスキル】ドキュメンテーションの続け方
忙しい研究者のためのテストコードとドキュメントの書き方 - Qiita
Please don't write your documentation in Markdown
最新の「Jupyter Book」を発表、Sphinxがベースに | OSDN Magazine
Announcing the new Jupyter Book
時雨堂は Sphinx の開発者である小宮健氏のプラチナスポンサーになりました
Meilisearch を利用して Sphinx で日本語全文検索を実現する
図解！Jupyter Notebookを徹底解説！(インストール・使い方・起動・終了方法) - ビジPy
Overview — Sphinx documentation
ふだん Markdown を書く技術者のための reStructuredText 文法まとめ
Sphinxのイケてるドキュメントを自動デプロイしてS3で公開する！ | DevelopersIO
Sphinx-2.4 で進化した型機能を使おう - Qiita
SphinxとLuaLaTeXで、日本語PDFマニュアルを作る - aptpod Tech Blog
GitBook がしれっと HonKit になってた件
静的サイトジェネレーターの選定時に考えること | himenon.github.io
GitHub Actionsを用いてGitHub Pagesへのデプロイを自動化する