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 中所做的更改，创建并标记为需要翻译的问题。

代码示例

所有代码引用都应与语言无关，并且代码本身应放置在代码选项卡内。

默认代码选项卡

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

这比编写代码注释更好，因为这些注释不会被翻译。 只包含文档所需的代码，避免过度解释。 最后，请记住不要缩进纯文本，否则它会呈现为代码块。