Improve Docs: contact part

[GaryDu0123]

1. 将JavaScript代码替换为python代码
2. 将文档翻译为中文
3. 小幅度修改了文档结构

[CLAassistant]

All committers have signed the CLA.

[wj-Mcat]

Your improvement is great. Are you interested in writing documentation for other modules? If so, it will be a great thing.

[GaryDu0123]

Your improvement is great. Are you interested in writing documentation for other modules? If so, it will be a great thing.

Sure, that will be my pleasure, I will request a new pr after I complete

[wj-Mcat]

I’m very glad to hear that. Our document and code need a lot of improvements which are opened for developers. So there are many challenging improvements on docs and codes.

Back to the point, you can put all changes at here and modify the title of pr. We are looking forward to your future great works. Please go head and feel free to discuss with us at here.

[GaryDu0123]

OK, I will change this PR title, and try to improve the references dir in recent days~ Cheers

[GaryDu0123]

Almost done, but I am not yet familiar with the methods and attributes in wechaty.md and Friendship.md , so I think I should just leave it here, hope someone can improve it in the future

[wj-Mcat]

Your improvements are so great, I think it will make a big change on docs of python-wechaty. Here are some suggestions about some detailed problem. Let's discuss about it.

[wj-Mcat]

There are some suggestions:

• the variable should be all lower case by python naming conventions. So the contactSelf should be contact_self that you can change lots of variables. How do you think about it?
• If the method is async-based, the typing of return result should be Coroutine, please refer to:
  • Document how to type hint for an async function used as a callback python/typing#424
  • Coroutine functions should return Coroutine, not Awaitable python/mypy#3569
  • So, I suggest that the return type annotation of async method is: Coroutine[..., ..., ...]
• if the result is None | FileBox which is the program language gramar in ts, it shoule be: Optional[Filebox]

[wj-Mcat]

@GaryDu0123 there are some discussion topic in outline comment, we can get deep into discussion about one of topic as sub-comment. eg this comment is the sub-comment about type annotations.

---

If you can not understand, let use the generated stubfile type annotation in pyi file. For example:

Here is the generated stubfile with subgen tools. You can have a detail look. The following code is the example:

class ContactSelf(Contact):
    async def avatar(self, file: Optional[FileBox] = ...) -> FileBox: ...
    async def qr_code(self) -> str: ...
    @property
    def name(self) -> str: ...
    @name.setter
    def name(self, name: Optional[str]) -> None: ...
    async def signature(self, signature: str) -> Any: ...

The suggested command is:

# install the mypy and stubgen  tools
pip install mypy

# generate stubfiles
stubgen -o ./src ./src

Please feel free to discuss more about this problem.

[huan]

Wechaty Contributors Nomination

Link to wechaty/PMC#16

[GaryDu0123]

Yea, I think you are right, it should be like Coroutine kind of things, and also for the contact_self, I will take a look at those issues and modify the commit,

[GaryDu0123]

I was trying to find the description of using Coroutine as a return type on the python docs, but in the end, I still did not fully understand how to use it. So I decided to keep the return type the same as the source code, hope it is acceptable lol

[wj-Mcat]

You have done a great improvement on docs, and it takes a while to read this. But here are some details to discuss, please read it and try to make another change. Looking forward to your next commit.

[wj-Mcat]

The type of return result is Optinal[FileBox].

[wj-Mcat]

I give a mention it by the way that it's more elegant to use overload at here which will make code clear and code complete more precise. The example code is:

@overload
async def avatar(self) -> FileBox: ...

@overload
async def avatar(self, file: FileBox) -> None: ...

There are many method should be refactored. If you have any interest at this python trick, It's will be great for you and python-wechaty.

[GaryDu0123]

Cool, I like the @overload way hahaha, thanks for your mention, I will modify my commit

[wj-Mcat]

ping @GaryDu0123 Looking forward to your new commit to fix the above issue.

[GaryDu0123]

ping @GaryDu0123 Looking forward to your new commit to fix the above issue.

coooool

[wj-Mcat]

LGTM

[GaryDu0123]

@huan Can I join Wechaty Contributor Program?

[huan]

Of course, and thank you very much for your contribution!

You are welcome to join Wechaty Contributor Program

1. Join Wechaty Organization

You've invited Gary Du to Wechaty! They'll be receiving an email shortly. They can also visit https://github.com/wechaty to accept the invitation.

I have invited you to join our Wechaty GitHub Organization, please accept it by following the above message. (See also: wechaty/PMC#16)

2. Update Your Wechaty Contributor Profile

1. Please open Contributor Hall of Fame and add yourself to the end of the list, so that other contributors will know you better!
2. Please add yourself to our Website Contributors by creating a PR and refer to this PR link as well.

3. Join The Contributor Only WeChat Room

We also have a WeChat room for contributors only which can discuss Wechaty at a deeper level, you are welcome to join and if you are interested.

Please add @lijiarui wechat: ruirui_0914 and send her this pr link. She will invite you into Wechaty Contributor Room

Cheers!

[GaryDu0123]

thanks