Selenium 文档的样式指南

阅读我们的 贡献文档，了解有关如何向此文档添加内容的完整说明。

警告

已添加提醒，将潜在贡献者直接引导至缺少特定内容的位置。

{{< alert-content />}}

或

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

显示如下

标题大小写

我们的文档对 linkTitle 使用标题大小写，它应该简短，对 title 使用句子大小写，它可以更长且更具描述性。例如，特殊标题 的 linkTitle 可能具有文档中特殊标题的重要性 的 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。如果只有部分选项卡使用此简码，请将 langEqualsHeader=true 保留在 tabpane 中，并将 text=true 添加到 tab。请注意，gh-codeblock 行根本不能缩进。

使用 gh-codeblock 的一大好处是它添加了一个指向完整示例的链接。这意味着您不必包含任何其他上下文代码，只需包含所需的行，用户就可以导航到仓库以查看如何使用它。

代码的基本比较如下所示

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

它看起来像这样

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

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

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

    let value = await message.getText();
    assert.equal("Received!", value);

        var textBox = driver.findElement(By.name("my-text"))
        val submitButton = driver.findElement(By.cssSelector("button"))

在选项卡中使用 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

        WebDriver driver = new ChromeDriver();

        driver.get("https://www.seleniumcn.cn/selenium/web/web-form.html");

        driver.quit();

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