Seleniumドキュメントのスタイルガイド

ドキュメントにコンテンツを追加する方法の詳細な手順については、貢献に関するドキュメントをお読みください。

アラート

特定のコンテンツが不足している箇所を潜在的な貢献者に指示するために、アラートが追加されました。

{{< alert-content />}}

または

{{< alert-content >}}
Additional information about what specific content is needed
{{< /alert-content >}}

これはこのように表示されます

タイトルの大文字表記

ドキュメントでは、短くする必要がある linkTitle にはタイトルケースを使用し、より長く記述的なものにできる title にはセンテンスケースを使用します。たとえば、Special Heading の linkTitle には、The importance of a special heading in documentation の title が設定される場合があります。

行の長さ

プレーンHTMLで記述されたドキュメントのソースを編集するときは、行の長さを約100文字に制限してください。

私たちの中には、さらに一歩進んで、セマンティック改行と呼ばれる手法を使用する人もいます。これは、一般公開されないHTMLソース行を、文章の「自然な区切り」で分割する手法です。言い換えれば、文は句間の自然な区切りで分割されます。各段落の行がすべて右マージン付近で終わるように調整する代わりに、アイデアの区切りがある場所ならどこにでも改行を追加できます。

これは、git を介して共同作業を行うときに差分を非常に読みやすくする可能性がありますが、貢献者に使用を強制するものではありません。

翻訳

Seleniumには、サポートされている各言語の公式翻訳者がいます。

• important_documentation.en.md ファイルにコード例を追加する場合は、important_documentation.ja.md、important_documentation.pt-br.md、important_documentation.zh-cn.md にも追加してください。
• 英語版でテキストを変更する場合は、プルリクエストを作成するだけです。新しいプロセスでは、特定のPRで行われた変更に基づいて、翻訳が必要なIssueが作成され、タグ付けされます。

コード例

コードへの参照はすべて言語に依存しないようにし、コード自体はコードタブ内に配置する必要があります。

デフォルトのコードタブ

Docsyのコードタブは次のようになります

• Java
• Python
• CSharp
• Ruby
• JavaScript
• Kotlin

WebDriver driver = new ChromeDriver();

driver = webdriver.Chrome()

var driver = new ChromeDriver();

driver = Selenium::WebDriver.for :chrome

let driver = await new Builder().forBrowser('chrome').build();

val driver = ChromeDriver()

上記のタブを生成するには、次のように記述する必要があります。tabpane に langEqualsHeader=true が含まれていることに注意してください。これにより、各タブのコードがヘッダー名に合わせて自動フォーマットされ、言語のあるページのすべてのタブが同じ設定になります。

{{< tabpane langEqualsHeader=true >}}
  {{< tab header="Java" >}}
    WebDriver driver = new ChromeDriver();
  {{< /tab >}}
  {{< tab header="Python" >}}
    driver = webdriver.Chrome()
  {{< /tab >}}
  {{< tab header="CSharp" >}}
    var driver = new ChromeDriver();
  {{< /tab >}}
  {{< tab header="Ruby" >}}
    driver = Selenium::WebDriver.for :chrome
  {{< /tab >}}
  {{< tab header="JavaScript" >}}
    let driver = await new Builder().forBrowser('chrome').build();
  {{< /tab >}}
  {{< tab header="Kotlin" >}}
    val driver = ChromeDriver()
  {{< /tab >}}
{{< /tabpane >}}

GitHubの例を参照

すべてのコードが最新の状態に保たれるように、私たちの目標は、Seleniumのバージョンが更新されたときに実行できるリポジトリにコードを記述して、すべてが正しいことを保証することです。

すべてのコード例は、example directories に含める必要があります。

このコードは、gh-codeblock ショートコードを使用してドキュメントに自動的に表示できます。ショートコードは独自のHTMLを自動的に生成するため、言語ヘッダーで自動フォーマットしたくありません。すべてのタブがこのショートコードを使用している場合は、tabpane で text=true を設定し、langEqualsHeader=true を削除します。一部のタブのみがこのショートコードを使用している場合は、tabpane で langEqualsHeader=true を保持し、tab に text=true を追加します。gh-codeblock 行はインデントできないことに注意してください。

gh-codeblock を使用することの素晴らしい点の1つは、完全な例へのリンクが追加されることです。これは、追加のコンテキストコードを含める必要がなく、必要な行のみを含めるだけで、ユーザーはリポジトリに移動してその使用方法を確認できることを意味します。

コードの基本的な比較は次のようになります

{{< tabpane text=true >}}
{{< tab header="Java" >}}
{{< gh-codeblock path="examples/java/src/test/java/dev/selenium/getting_started/FirstScript.java#L26-L27" >}}
{{< /tab >}}
{{< tab header="Python" >}}
{{< gh-codeblock path="examples/python/tests/getting_started/first_script.py#L18-L19" >}}
{{< /tab >}}
{{< tab header="CSharp" >}}
{{< gh-codeblock path="examples/dotnet/SeleniumDocs/GettingStarted/FirstScript.cs#L25-L26" >}}
{{< /tab >}}
{{< tab header="Ruby" >}}
{{< gh-codeblock path="examples/ruby/spec/getting_started/first_script.rb#L17-L18" >}}
{{< /tab >}}
{{< tab header="JavaScript" >}}
{{< gh-codeblock path="examples/javascript/test/getting_started/firstScript.spec.js#L22-L23" >}}
{{< /tab >}}
{{< tab header="Kotlin" >}}
{{< gh-codeblock path="examples/kotlin/src/test/kotlin/dev/selenium/getting_started/FirstScriptTest.kt#L31-L32" >}}
{{< /tab >}}
{{< /tabpane >}}

これは次のようになります

• Java
• Python
• CSharp
• Ruby
• JavaScript
• Kotlin

        WebElement message = driver.findElement(By.id("message"));
        message.getText();

message = driver.find_element(by=By.ID, value="message")
text = message.text

        var message = driver.FindElement(By.Id("message"));
        var value = message.Text;

message = driver.find_element(id: 'message')
message.text

    let message = await driver.findElement(By.id('message'));
    let value = await message.getText();

        val message = driver.findElement(By.id("message"))
        val value = message.getText()

タブでのMarkdownの使用

例にコード（デフォルト）またはhtml（gh-codeblockから）以外のものを含める場合は、最初に text=true を設定し、次に tab のHugo構文を < および > の代わりに % と中括弧を使用するように変更する必要があります。

{{< tabpane text=true >}}
{{% tab header="Java" %}}
1. Start the driver
{{< gh-codeblock path="examples/java/src/test/java/dev/selenium/getting_started/FirstScript.java#L12" >}}
2. Navigate to a page
{{< gh-codeblock path="examples/java/src/test/java/dev/selenium/getting_started/FirstScript.java#L14" >}}
3. Quit the driver
{{< gh-codeblock path="examples/java/src/test/java/dev/selenium/getting_started/FirstScript.java#L29" >}}
{{% /tab %}}
< ... >
{{< /tabpane >}}

これは生成されます

• Java

これは、コードコメントを記述するよりも推奨されます。なぜなら、コードコメントは翻訳されないからです。ドキュメントに必要なコードのみを含め、過剰な説明は避けてください。最後に、プレーンテキストをインデントしないように注意してください。インデントするとコードブロックとしてレンダリングされます。