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 協作時，這可以讓 diff 非常容易閱讀，但我們不會強制貢獻者使用。

翻譯

Selenium 現在為每種支援的語言都有官方翻譯人員。

• 如果您在 important_documentation.en.md 檔案中新增程式碼範例，也請將其新增至 important_documentation.ja.md、important_documentation.pt-br.md、important_documentation.zh-cn.md。
• 如果您在英文版本中進行文字變更，只需提出 Pull Request 即可。新流程是根據給定 PR 中所做的變更，建立並標記為需要翻譯的問題。

程式碼範例

所有程式碼參考都應獨立於語言，且程式碼本身應放置在程式碼標籤頁中。

預設程式碼標籤頁

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 版本更新時可以執行程式碼，以確保一切正確。

所有程式碼範例都位於我們的範例目錄中。

可以使用 gh-codeblock 簡碼在文件中自動顯示此程式碼。簡碼會自動產生自己的 html，因此我們不希望它使用語言標題自動格式化。如果所有標籤頁都使用此簡碼，請在 tabpane 中設定 text=true 並移除 langEqualsHeader=true。如果只有部分標籤頁使用此簡碼，請在 tabpane 中保留 langEqualsHeader=true，並在 tab 中新增 text=true。請注意，gh-codeblock 行完全不能縮排。

使用 gh-codeblock 的一大優點是它會新增一個連結到完整範例。這表示您不必包含任何額外的上下文程式碼，只需包含所需的行，使用者就可以導航到儲存庫以查看如何使用它。

程式碼的基本比較看起來像這樣

{{< 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

這是比撰寫程式碼註解更好的做法，因為這些註解不會被翻譯。僅包含文件所需的程式碼，並避免過度解釋。最後，請記住不要縮排純文字，否則會將其呈現為程式碼區塊。