文書を作成する

高品質で一致した天文コード文書はAstropyプロジェクトの主要な目標の一つである。したがって、私たちはここで私たちの文書手続きと規則を説明する。Asterpyコアプロジェクトや協調パッケージについては，可能な限りこれらに従うことを奨励し，専門天文ソフトウェアにしばしば不足している特徴である有用な文書を奨励するため，付属パッケージもこれらに従うことを奨励している。

Gitを追加して提出する

変更がドキュメント(すなわちdocstringまたはrstファイル)にのみ影響を与え、doctestを実行するために必要なコードセグメントが何も含まれていない場合には、追加することができます [ci skip] あなたの提出メッセージにあります。例えば：

git commit -m "Update documentation about this and that [ci skip]"

このコミットをプル型要求に関連する分岐機構にプッシュする場合，必要ではないため，すべての配置項がスキップされる.これは，文書バージョンがRTDに存在し，RTDが現在サポートされていないためである. [ci skip] 指令する。

ソースコードから文書を構築する

ソースコードから文書を生成する情報については、参照 建築文書. 実装説明の1節.

Astropy文書ルールとガイド

本節では，カーネルパッケージに統合された任意の貢献を考慮して従うべき文書基準と，標準的なAstropy文書文字列フォーマットについて述べる.

  • すべての文書テキストはすぐに続くべきである Astropyナラティブ·スタイルガイド：投稿者用の執筆資源 それがそうです。

  • すべての文書は使用すべきである Sphinx 文書ツールです。

  • ♪the package template 推薦された文書汎用構造を提供する.

  • すべての共通クラス、方法、そして関数にDocstringを提供しなければならない。

  • Docstringはついてくるべきです numpydoc format それがそうです。

  • 特定のモジュールまたはクラスの典型的な用例の場合、使用例および/またはチュートリアルが強く提案される。

  • どんな外部パッケージ依存項も文書で明確に言及されなければならない。これらも記録すべきです setup.cfg Astpyリポジトリのルートディレクトリで使用 extras_require 入る。

  • オプションの構成使用 astropy.config メカニズムは文書で明確に言及されなければならない。

Sphinx文書トピック

Astropy Project Sphinx HTMLトピックは astropy-sphinx-theme 小包です。これにより、Astropyおよびアクセサリパッケージの両方がこのトピックを使用することができる。このトピックは、グローバルAstropy Shinx構成でトピックを設定することによって活性化されます。 sphinx-astropy, これは、Astropyと付属ソフトウェアパッケージの獅子面像構成に導入されます。

グローバル構成に設定されたいくつかのShinx構成変数をカバーすることで、異なる引数を使用することができる。

  • 異なるテーマをご利用の場合は、設定してください html_theme Sphinx引数またはカスタムトピックの名前を内蔵する必要があります。 package-name/docs/conf.py (凡人) 'package-name' “Astpy”または付属パッケージの名前です)。

  • カスタムトピックを使用するには、以下の操作を別途実行してください：トピックを配置する package-name/docs/_themes 追加します '_themes' 致す html_theme_path 変数です。ご参照ください Sphinx 主題の詳細については、文書を参照されたい。

ライオンの顔像が広がる

Astropyの文書構築プロセスは多くのShinx拡張を用いており，これらの拡張は実装時に自動的に実装されている. sphinx-astropy. これらは、同じ構成および可読な方法でコードを容易に記録することを容易にする。

使用の主な拡張は：

  • sphinx-automodapi -API文書の自動生成が容易な拡張。

  • sphinx-gallery -インスタンスライブラリを生成するための拡張

  • numpydoc -NumpyDoc形式の文書文字列を解析するための拡張

また、 sphinx-astropy いくつかの小さな拡張が含まれています

  • sphinx_astropy.ext.edit_on_github -文書ページに“GitHubで編集する”リンクの拡張を追加します。

  • sphinx_astropy.ext.changelog_links ·ChangeLogが提示されたときに要求の拡張を引き出すためのリンクを追加するステップと。

  • sphinx_astropy.ext.doctest -文書テストに関するメタデータを内部に追加することを可能にする拡張 .rst 書類