修改部分难以理解的语法、冗长的语法、警告信息

[jimcat8]

Author checklist (to be completed by original Author)

• Is this document a good fit for the Rocky project ?
• Is this a non-English contribution?
• Title and Author MetaTags have been inserted into the document
• If applicable, steps and instructions have been tested to work on a real system
• Did you perform an initial self-review to fix basic typos and grammatical correctness

Rocky Documentation checklist (to be completed by Rocky team)

• 1st Pass (Check that document is good fit for project and author checklist completed)
• 2nd Pass (Technical Review - check for technical correctness)
• 3rd Pass (Basic Editorial Review)
• 4th Pass (Detailed Editorial Review and Peer Review)
• 5th Pass (Include document in TOC)
• Final pass/approval (Final Review)

[justasojourner]

Hi @jimcat8

Thanks for your recent update. I had a look at it, just need to share that at the moment the Contributions home page is being considered for a revamp and the page will very likely change so at this time it is best not to put any work into it.

We are actually looking to extend/enhance the technical parts of the Contribution Guide (Git, GitHub, workflow) part of the docs website to share expanded information with everyone.

It's great that you did a translation of it, having translations for the contribution section is very helpful. I previously posted a lot of information about localised versions of documents which obviously does not relate to your recent document because it is outside of the main website. It actually might be a good idea to have the Contribution Guide content (given that translations are a good thing) as part of the main website so it can use the multiple language support of MkDocs.

[justasojourner]

Hi @jimcat8

Found a couple of problems with the home page, basically they come down to the point that MkDocs requires Markdown directives to be in English.

Menu title

Displays as this:

This is because the meta tag is this

---
标题：首页
---

But should be this

---
title：Home
---

Or, if translation of the top level menu text is desired, this:

---
title：首页
---

But the meta tag title must be in English for MkDocs to understand it. If there is no document title meta tag then MkDocs falls back to the name of the document, which is index, into the menu which is not good.

Admonition

The admonition in the page currently looks like this:

but should be this, the admonition element shown:

The tag for admonitions must not be translated, and the !!! must not have any spaces and the admonition text must be indented by four spaces

So not this:

！！！笔记
    并非所有功能都适用于所有语言，这是可用的底层 MkDocs 模块的限制。

but this :

!!! note
    并非所有功能都适用于所有语言，这是可用的底层 MkDocs 模块的限制。

Cross ref. the original:

!!! note
    Not all functionality may be available in all languages, this is a limitation of the underlying MkDocs modules available.

UPDATE
I see in the Python Markdown documentation https://python-markdown.github.io/extensions/admonition/

that a custom title is possible, so this:

!!! note "笔记"
    并非所有功能都适用于所有语言，这是可用的底层 MkDocs 模块的限制。

Should work.

UPDATE 2

It works fine, I just tested it on a test MkDocs installation:

as the admonition is of type note it has the same blue outline as the English version. Other admonition types like warning and danger have different colours.

[sspencerwire]

Thanks, @jimcat8 for the time and effort you have put into this. I wanted to let you know that I'm going to merge the Installation Guide and the Index changes. We are going to be making some changes to the Contribution section that will involve the README.md files. Because of the language selector at the top of the documentation website, you should not need to link to the two version within each README, but rather than changing that, based on the changes that are coming, I'm going to delete those two files in the PR for now. Keep watch on the site for upcoming changes and I will welcome your edits to those pages when the time comes. Thanks again for your work! Keep it up! We need more translators!