Pylons プロジェクト配下のプロジェクトは、コーディングスタイル、テスト、 およびドキュメンテーションに関する厳格な標準を持っています。
すべてのプロジェクトは Sphinx を用いて ドキュメンテーションを構築する必要があり、一貫性のため Pylons Sphinx Theme を使用します。
Pylons テーマを使用してドキュメンテーションを構築するためには、 Sphinx の conf.py の先頭付近に次の定型文を加えてください:
import sys, os
# Add and use Pylons theme
# protect against dumb importers
if 'sphinx-build' in ' '.join(sys.argv):
from subprocess import call, Popen, PIPE
p = Popen('which git', shell=True, stdout=PIPE)
git = p.stdout.read().strip()
cwd = os.getcwd()
_themes = os.path.join(cwd, '_themes')
if not os.path.isdir(_themes):
call([git,
'clone',
'git://github.com/Pylons/pylons_sphinx_theme.git',
'_themes'])
else:
os.chdir(_themes)
call([git, 'checkout', 'master'])
call([git, 'pull'])
os.chdir(cwd)
sys.path.append(os.path.abspath('_themes'))
parent = os.path.dirname(os.path.dirname(__file__))
sys.path.append(os.path.abspath(parent))
os.chdir(parent)
html_theme_path = ['_themes']
html_theme = 'pylons'
html_theme_options = {github_url:'https://github.com/Pylons/yourprojname'}
そして、この結果作られる _themes ディレクトリをバージョン管理システムの 中で無視するようにしてください。
これによってテーマを利用するプロジェクトを構築することが可能になります。 また、テーマに更新があった場合、ドキュメントが再構築される時にテーマの 変更が自動的に取得されます。
docs/conf.py の中で latex_documents に以下の値を設定してください:
# Grouping the document tree into LaTeX files. List of tuples
# (source start file, target name, title, author, document class [howto/manual]).
latex_documents = [
('latexindex', 'pyramid_<project name>.tex',
'Pyramid\_<project name>',
'Author', 'manual'),
]
LaTeX でのエラーを防ぐため、 \_ を使用してドキュメントタイトル中の下線 をエスケープすることは重要です。
以下の行をコメントにしてください:
#latex_logo = '_static/pylons_small.png'
フォルダ pyramid/docs/_static (2つの .png ファイルを含む) と、ファイル pyramid/docs/convert_images.sh を docs/ フォルダにコピーしてください。
docs/conf.py の中で epub_exclude_files に以下の値を必ず設定してください:
# A list of files that should not be packed into the epub file.
epub_exclude_files = ['_static/opensearch.xml', '_static/doctools.js',
'_static/jquery.js', '_static/searchtools.js', '_static/underscore.js',
'_static/basic.css', 'search.html', '_static/websupport.js' ]
Pylons プロジェクトのすべてのパッケージで、機能を加えるために:
上記の必要条件は paster テンプレート依存性について緩められます。 paster テンプレートが特定のプラットフォーム上で動作しないインストール時 の依存性を持っている場合、 その (docs/ ディレクトリ内にある) ドキュメンテーションの中ではっきりと警告が書かれていなければなりません
ある機能を既存のパッケージに加えるべきか、それとも単独のパッケージと するのが相応しいかどうかを判断するために、遠慮なく開発者チームの誰かに 話しかけてください。
あなたがバグを直し、そのバグが API または振る舞いの修正を必要とする場合、 その API または振る舞いを参照するパッケージ中のすべてのドキュメンテーション はバグフィックスを反映して変更しなければなりません。バグを修正する、または 機能を追加するのと同じコミットの中で行われるのが理想的です。
機能追加とバグフィックスは、一般的なスタイルで CHANGES.txt ファイル に加えられなければなりません。 Changelog エントリは、暗号的でなく長文で 記述的であるべきです。他の開発者があなたの changelog エントリの意味を 理解できなければなりません。
コードベースは各コミットの後で 100% のテスト行カバレージを持って いなければなりません。 python setup.py nosetests --with-coverage によってカバレージをテストすることができます (nose と coverage パッケージが必要です)。
一貫したやり方でコードをテストすることは困難かもしれません。テストに 関する私たちのスタイル (「ドグマ(教義)」) を開発者が学習するのを助ける ため、テストに関する諸注意を 単体テストガイドライン に用意しています。
すべての Python コードは PEP-8 スタイルガイドラインに 従ってください。空白に関するルールは緩められ、クラス間に2行の空行を 置くことは必須ではありません (そうすることはまったく問題ありませんが)。 特に 1行 80 カラムは必ず守ってください。
単一行のインポート
このようにしてください:
1 2 | import os
import sys
|
このように しないで ください:
1 | import os, sys
|
1行につき1つインポートすることは、パッチを読んだり差分をコミットする ことをより簡単にします。
単一のパッケージから数多くの名前をインポートする必要がある場合は、次の 書式を使用してください:
from thepackage import (
foo,
bar,
baz,
)
インポート順
インポートはその起源の順で並べなければなりません。名前は以下の順で インポートすべきです:
ワイルドカードインポート
あるパッケージからすべての名前をインポートしては なりません (例えば from package import * を使用しないでください)。必要なものだけを インポートしてください。ここで、単一行インポートも同様に適用されます。 別のパッケージからのそれぞれの名前は、別々の行でインポートしなければ なりません。
デフォルト引数として変更可能オブジェクトを使用しない
Python は関数/メソッドのデフォルト引数をたった一度だけ解析するので、 それらをデフォルト引数として安全に使用できないということを忘れないで ください。
このように しないで ください:
1 2 3 | def somefunc(default={}):
if default.get(...):
...
|
これらのどちらかであれば構いません:
1 2 | def somefunc(default=None):
default = default or {}
|
1 2 3 | def somefunc(default=None):
if default is None:
default = {}
|
人々がインポート時の副作用に依存せざるをえないようにすることは極めて 推奨されません。
何らかのモジュールスコープのコードを実行するという単一の目的のためだけに モジュールやパッケージをインポートすることを誰かに要求するコードの作成は、 極めて推奨されません。コアの中で paster テンプレートにそのようなコードを 追加することだけは許されています。そうしたことは、他のフレームワークに よって必要とされる場合があります (例えば、 SQLAlchemy “declarative base” クラスが登録されるためにはインポートされる必要があります)。