Documentation Standards ¶

Sphinx ¶

• The following characters are chosen for different heading levels: level 1 is = (equal sign), level 2 - (dash), level 3 ~ (tilde), level 4 . (dot) and level 5 " (double quote);
  次の文字は、さまざまな見出しレベルに対して選択されます: レベル 1is = (等号)、レベル 2 - (ダッシュ)、レベル 3 ~ (チルダ)、レベル 4. (ドット)、およびレベル 5 " (二重引用符)。
• Each line should break approximately after the first word that crosses the 72nd character (so most lines end up being 72-78 characters);
  各行は、およそ 72 番目の文字を横切る最初の単語の後で改行する必要があります (したがって、ほとんどの行は最終的に 72 ～ 78 文字になります)。
• The :: shorthand is preferred over .. code-block:: php to begin a PHP code block unless it results in the marker being on its own line (read the Sphinx documentation to see when you should use the shorthand);
  PHPcode ブロックを開始するには、.. code-block:: php よりも短縮形 :: を使用することをお勧めします。
• Inline hyperlinks are not used. Separate the link and their target definition, which you add on the bottom of the page;
  インライン ハイパーリンクは使用されません。ページの下部に追加するリンクとそのターゲット定義を分離します。
• Inline markup should be closed on the same line as the open-string;
  インライン マークアップは、開いている文字列と同じ行で閉じる必要があります。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

Example
=======

When you are working on the docs, you should follow the
`Symfony Documentation`_ standards.

Level 2
-------

A PHP example would be::

    echo 'Hello World';

Level 3
~~~~~~~

.. code-block:: php

    echo 'You cannot use the :: shortcut here';

.. _`Symfony Documentation`: https://symfony.com/doc

Code Examples ¶

• The code follows the Symfony Coding Standards as well as the Twig Coding Standards;
  コードは、Symfony コーディング標準と Twig コーディング標準に従っています。
• The code examples should look real for a web application context. Avoid abstract or trivial examples (foo, bar, demo, etc.);
  コード例は、Web アプリケーションのコンテキストで実際に見えるはずです。抽象化の単純な例 (foo、bar、demo など) は避けてください。
• The code should follow the Symfony Best Practices.
  コードは Symfony のベスト プラクティスに従う必要があります。
• Use Acme when the code requires a vendor name;
  コードにベンダー名が必要な場合は Acme を使用します。
• Use example.com as the domain of sample URLs and example.org and example.net when additional domains are required. All of these domains are reserved by the IANA.
  サンプル URL のドメインとして example.com を使用し、追加のドメインが必要な場合は example.org および example.net を使用します。これらのドメインはすべて IANA によって予約されています。
• To avoid horizontal scrolling on code blocks, we prefer to break a line correctly if it crosses the 85th character;
  コード ブロックでの水平スクロールを避けるために、行が 85 番目の文字を超える場合は行を正しく分割することをお勧めします。
• When you fold one or more lines of code, place ... in a comment at the point of the fold. These comments are: // ... (PHP), # ... (Yaml/bash), {# ... #} (Twig), <!-- ... --> (XML/HTML), ; ... (INI), ... (text);
  1 行または複数行のコードを折りたたむ場合は、折りたたみのポイントで ... をコメントに入れます。これらのコメントは次のとおりです: // ... (PHP), # ... (Yaml/bash), {# ... #}(Twig),(XML/HTML), ; ... (INI), ... (テキスト);
• When you fold a part of a line, e.g. a variable value, put ... (without comment) at the place of the fold;
  線の一部を折りたたむとき。可変値、折り畳みの場所に ... (コメントなし) を入れます。

• Description of the folded code: (optional)

  折りたたまれたコードの説明: (オプション)
  • If you fold several lines: the description of the fold can be placed after the ...;
    複数の行を折りたたむ場合: 折りたたみの説明は ...; の後に配置できます。
  • If you fold only part of a line: the description can be placed before the line;
    線の一部のみを折りたたむ場合: 説明を線の前に配置できます。
• If useful to the reader, a PHP code example should start with the namespace declaration;
  読者にとって有用な場合、PHP コード例は名前空間宣言から始めるべきです。
• When referencing classes, be sure to show the use statements at the top of your code block. You don't need to show all use statements in every example, just show what is actually being used in the code block;
  クラスを参照するときは、必ずコード ブロックの先頭に use ステートメントを表示してください。すべての例ですべての use ステートメントを表示する必要はありません。コード ブロックで実際に使用されているものを表示するだけです。
• If useful, a codeblock should begin with a comment containing the filename of the file in the code block. Don't place a blank line after this comment, unless the next line is also a comment;
  有用な場合、コード ブロックは、コード ブロック内のファイルのファイル名を含むコメントで開始する必要があります。次の行もコメントでない限り、このコメントの後に空白行を置かないでください。
• You should put a $ in front of every bash line.
  すべての bash 行の前に $ を置く必要があります。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

// src/Foo/Bar.php
namespace Foo;

use Acme\Demo\Cat;
// ...

class Bar
{
    // ...

    public function foo($bar)
    {
        // set foo with a value of bar
        $foo = ...;

        $cat = new Cat($foo);

        // ... check if $bar has the correct value

        return $cat->baz($bar, ...);
    }
}

Files and Directories ¶

• When referencing directories, always add a trailing slash to avoid confusions with regular files (e.g. "execute the console script located at the bin/ directory").
  ディレクトリを参照するときは、通常のファイルとの混乱を避けるために、必ず末尾にスラッシュを追加してください (例: 「bin/ディレクトリにあるコンソール スクリプトを実行します」)。
• When referencing file extensions explicitly, you should include a leading dot for every extension (e.g. "XML files use the .xml extension").
  ファイル拡張子を明示的に参照する場合は、すべての拡張子の先頭にドットを含める必要があります (例: 「XML ファイルは .xml 拡張子を使用します」)。

• When you list a Symfony file/directory hierarchy, use your-project/ as the top-level directory. E.g.

  Symfony のファイル/ディレクトリ階層を一覧表示するときは、your-project/ を最上位ディレクトリとして使用します。例えば。

  1 2 3 4 5

  your-project/ ├─ app/ ├─ src/ ├─ vendor/ └─ ...

English Language Standards ¶

Symfony documentation uses the United States English dialect, commonly called American English. The American English Oxford Dictionary is used as the vocabulary reference.

In addition, documentation follows these rules:

• Section titles: use a variant of the title case, where the first word is always capitalized and all other words are capitalized, except for the closed-class words (read Wikipedia article about headings and titles).

  セクション タイトル: タイトル ケースのバリエーションを使用します。最初の単語は常に大文字で、他のすべての単語は大文字で始まります。クローズド クラスの単語は除きます (見出しとタイトルに関するウィキペディアの記事を参照してください)。

  E.g.: The Vitamins are in my Fresh California Raisins

  例: ビタミンは新鮮なカリフォルニア レーズンに含まれています
• Punctuation: avoid the use of Serial (Oxford) Commas;
  句読点: シリアル (オックスフォード) カンマの使用は避けてください。
• Pronouns: avoid the use of nosism and always use you instead of we. (i.e. avoid the first person point of view: use the second instead);
  代名詞: nosism の使用を避け、常に we の代わりに you を使用します (つまり、一人称視点を避け、代わりに 2 人称視点を使用します)。

• Gender-neutral language: when referencing a hypothetical person, such as "a user with a session cookie", use gender-neutral pronouns (they/their/them). For example, instead of:

  性別を問わない言葉遣い: 「セッション Cookie を持つユーザー」など、架空の人物に言及する場合は、性別を問わない代名詞 (they/their/them) を使用します。たとえば、次のように:
  • he or she, use they
    彼または彼女は、それらを使用します
  • him or her, use them
    彼または彼女、それらを使用してください
  • his or her, use their
    彼または彼女は、彼らの
  • his or hers, use theirs
    彼または彼女のもの、彼らのものを使用
  • himself or herself, use themselves
    自分自身、自分自身を使う

• Avoid belittling words: Things that seem "obvious" or "simple" for the person documenting it, can be the exact opposite for the reader. To make sure everybody feels comfortable when reading the documentation, try to avoid words like:

  軽蔑的な言葉を避ける: 文書化する人にとっては「明白」または「単純」に見えることは、読者にとっては正反対である可能性があります。誰もが安心してドキュメントを読むことができるように、次のような言葉は避けてください。
  • basically
    基本的に
  • clearly
    明らかに
  • easy/easily
    簡単に/簡単に
  • just
    ただ
  • logically
    論理的に
  • merely
    単に
  • obviously
    明らかに
  • of course
    もちろん
  • quick/quickly
    早く/早く
  • simply
    単に
  • trivial
    些細な