From ericirrgang at gmail.com Wed Oct 9 04:42:51 2019 From: ericirrgang at gmail.com (Eric Irrgang) Date: Wed, 9 Oct 2019 11:42:51 +0300 Subject: [Doc-SIG] Python standard library documentation flavors Message-ID: Hello, I am trying to understand the relationship between the Python standard library docstrings and the online documentation. For example, it does not appear that https://raw.githubusercontent.com/python/cpython/master/Doc/library/collections.rst is a strict superset of the docstrings in https://github.com/python/cpython/blob/master/Lib/collections/__init__.py and I do not see any indication that docstrings are automatically extracted anywhere, nor any comment as to why or why not. Is there a standing decision *not* to use, say, sphinx-apidoc or sphinx.ext.autodoc? If so, can you point me to an explanation of how the benefits of fully human-maintained documentation outweigh the convenience and consistency of automation? In other words, is this an affirmative policy decision that other projects should be guided by, or an accident of history with a lesson to be learned? Is there a document that clarifies the role of the standard library docstrings, and what belongs there versus in cpython/Doc/library? Maybe there is a PEP I haven't noticed? I hope my question is not too open-ended for this list, but I would also welcome replies off list. Thank you for your time, Eric -------------- next part -------------- An HTML attachment was scrubbed... URL: From oon.arfiandwi at gmail.com Mon Oct 14 09:52:27 2019 From: oon.arfiandwi at gmail.com (oon arfiandwi) Date: Mon, 14 Oct 2019 21:52:27 +0800 Subject: [Doc-SIG] Python Documentation Translation to Bahasa Indonesia (Indonesian Language) Message-ID: Dear doc-sig members, hope this email finds you well. my name is oon arfiandwi, currently, I'm doing a sprint to translate Python Documentation to Bahasa Indonesia, and in the next few days, it will achieve the minimum requirement, which mentioned on PEP 545, to be able to add to Language Switcher. The translation synchronized between Transifex and my github repo [1]. I have several questions before I continue the process: a. according to devguide site [2], I need to finish `library/stdtypes` too, but it is not mentioned on (current PEP 545). can someone help me to clarify which one is the minimum? b. I saw on Python's github repo, many python-doc-{LANG} hosted there, how to request `python-doc-id` on that repository? c. Is it mandatory to have reviewer on Transifex? I saw not many languages doing reviews on the translation there. d. and what to do next, if I have completed the translations (a), to be included on language switcher? thank you for any help and explanation. [1]: https://github.com/oonid/python-docs-id [2]: https://devguide.python.org/documenting/#starting-a-new-translation -- sincerely, oon arfiandwi -------------- next part -------------- An HTML attachment was scrubbed... URL: From julien at palard.fr Mon Oct 14 17:25:29 2019 From: julien at palard.fr (Julien Palard) Date: Mon, 14 Oct 2019 21:25:29 +0000 Subject: [Doc-SIG] Python standard library documentation flavors In-Reply-To: References: Message-ID: Hi Eric, > I am trying to understand the relationship between the Python standard library docstrings and the online documentation. Both are documentation is probably the only relationship. > For example, it does not appear that https://raw.githubusercontent.com/python/cpython/master/Doc/library/collections.rst is a strict superset of the docstrings in https://github.com/python/cpython/blob/master/Lib/collections/__init__.py That's right. > and I do not see any indication that docstrings are automatically extracted anywhere, nor any comment as to why or why not. > Is there a standing decision *not* to use, say, sphinx-apidoc or sphinx.ext.autodoc? If so, can you point me to an explanation of how the benefits of fully human-maintained documentation outweigh the convenience and consistency of automation? They are not automatically extracted and we don't want to: docstrings are documenting things one by one without context, only local facts, see PEP 257: "Do that, returns that.". Documentation in the other hand should be present an overview, provide jump tables, hyperlinks, contexts, examples, what to avoid, ... like: https://docs.python.org/3/library/asyncio.html does. > In other words, is this an affirmative policy decision that other projects should be guided by, or an accident of history with a lesson to be learned? I don't want to tell what other project should do and there may exist projects with successfull autogenerated documentation (maybe search around "literate programming", I bet they have nice examples). Anyway having an auto-generated documentation is probably better than no documentation. Here, in cpython, docstrings are usefull to the reader in need of information about a single thing, locally (in an IDE tooltip or calling help() in the REPL) while documentation is usefull to learn and to understand how to use something. > Is there a document that clarifies the role of the standard library docstrings, and what belongs there versus in cpython/Doc/library? Maybe there is a PEP I haven't noticed? There's PEP 257, not much I heard of. Bests, --? Julien Palard https://mdk.fr From julien at palard.fr Mon Oct 14 18:15:23 2019 From: julien at palard.fr (Julien Palard) Date: Mon, 14 Oct 2019 22:15:23 +0000 Subject: [Doc-SIG] Python Documentation Translation to Bahasa Indonesia (Indonesian Language) In-Reply-To: References: Message-ID: Hi oon arfiandwi, > currently, I'm doing a sprint to translate Python Documentation to Bahasa Indonesia, > and in the next few days, it will achieve the minimum requirement, > which mentioned on PEP 545, to be able to add to Language Switcher. Nice to read \o/ > I have several questions before I continue the process: > > a. according to devguide site [2], I need to finish `library/stdtypes` too, but it is not mentioned on (current PEP 545). can someone help me to clarify which one is the minimum? PEP 545 wins, I'll fix the devguide, thanks for noticing. > b. I saw on Python's github repo, many python-doc-{LANG} hosted there, how to request `python-doc-id` on that repository? You can either transfer the repository to the python organization (clean way I think) or ask me to create one on the python organization and give you permissions on it. If you choose to transfer the repository it's a two step process: - First transfer it to me (github.com/JulienPalard), trust me I'm the PEP 545 author I won't steal the repo :] - Then I'll transfer it to the Python organization. It's because to transfer to an organization you need the right to create a repo in it [1]. > c. Is it mandatory to have reviewer on Transifex? I saw not many languages doing reviews on the translation there. That's not mandatory, yet if you want a good quality I think reviewing is a good step. In France we don't use Transfiex because we're using github pull requests to proofread a lot, and a lot of mistakes are catched at this step [2]. > d. and what to do next, if I have completed the translations (a), to be included on language switcher? Once the repository migrated, open a PR to add your language here: https://github.com/python/docsbuild-scripts/blob/master/build_docs.py#L62 It will build your doc on the server and make it available on docs.python.org so you can check if everything's OK before opening to the public. If everything renders correctly you'll have to open another pull request to add your language to the switcher here: https://github.com/python/cpython/blob/master/Doc/tools/static/switchers.js#L21 [1]: https://help.github.com/en/articles/transferring-a-repository [2]: https://github.com/python/python-docs-fr/pull/886 Bests, --? Julien Palard https://mdk.fr From oon.arfiandwi at gmail.com Tue Oct 15 04:27:10 2019 From: oon.arfiandwi at gmail.com (oon arfiandwi) Date: Tue, 15 Oct 2019 16:27:10 +0800 Subject: [Doc-SIG] Python Documentation Translation to Bahasa Indonesia (Indonesian Language) In-Reply-To: References: Message-ID: Hi Julien, thank you for the clear explanation. On Tue, Oct 15, 2019 at 6:15 AM Julien Palard wrote: > > > I have several questions before I continue the process: > > > > a. according to devguide site [2], I need to finish `library/stdtypes` > too, but it is not mentioned on (current PEP 545). can someone help me to > clarify which one is the minimum? > > PEP 545 wins, I'll fix the devguide, thanks for noticing. > > great, hope it will encourage more team to comply with PEP 545. > > b. I saw on Python's github repo, many python-doc-{LANG} hosted there, > how to request `python-doc-id` on that repository? > > You can either transfer the repository to the python organization (clean > way I think) or ask me to create one on the python organization and give > you permissions on it. > If you choose to transfer the repository it's a two step process: > - First transfer it to me (github.com/JulienPalard), trust me I'm the PEP > 545 author I won't steal the repo :] > - Then I'll transfer it to the Python organization. > > I have transferred the 'python-docs-id' repository to your account. please don't steal it. :D I will wait for the repository available on python organization. \o/ > > c. Is it mandatory to have reviewer on Transifex? I saw not many > languages doing reviews on the translation there. > > That's not mandatory, yet if you want a good quality I think reviewing is > a good step. In France we don't use Transfiex because we're using github > pull requests to proofread a lot, and a lot of mistakes are catched at this > step [2]. > > hm, it's very good example. will gather more people to work on it. > > d. and what to do next, if I have completed the translations (a), to be > included on language switcher? > > Once the repository migrated, open a PR to add your language here: > https://github.com/python/docsbuild-scripts/blob/master/build_docs.py#L62 > > It will build your doc on the server and make it available on > docs.python.org so you can check if everything's OK before opening to the > public. > > If everything renders correctly you'll have to open another pull request > to add your language to the switcher here: > https://github.com/python/cpython/blob/master/Doc/tools/static/switchers.js#L21 > > I will do this part later, I think I need to test build with 'docsbuild-scripts' first at a local machine. -- sincerely, oon arfiandwi -------------- next part -------------- An HTML attachment was scrubbed... URL: From julien at palard.fr Tue Oct 15 09:31:51 2019 From: julien at palard.fr (Julien Palard) Date: Tue, 15 Oct 2019 13:31:51 +0000 Subject: [Doc-SIG] Python Documentation Translation to Bahasa Indonesia (Indonesian Language) In-Reply-To: References: Message-ID: o/ > I will wait for the repository available on python organization. \o/ Done: https://github.com/python/python-docs-id/ > I will do this part later, I think I need to test build with 'docsbuild-scripts' first at a local machine. You can run a test build locally, like the README says (read the docsbuild-script README there's some important mkdir and venv setup) but adding a --language and a --branch: python3 ./build_docs.py --quick --build-root build_root --www-root www --log-directory logs --group $(id -g) --skip-cache-invalidation --branch 3.8 --languages id The you can browse the doc using: python3 -m http.server -d www/ Tell me how it goes. --? Julien Palard https://mdk.fr From cocoatomo77 at gmail.com Tue Oct 15 12:07:16 2019 From: cocoatomo77 at gmail.com (tomo cocoa) Date: Wed, 16 Oct 2019 01:07:16 +0900 Subject: [Doc-SIG] Looking for language coordinators Message-ID: Hello, all translators First of all, I like to celebrate the GA release of Python 3.8 and congratulate all members related to this release!! I send this email, because I want to share roles on the Transifex project. Currently, all join requests and adding languages requests are approved by me, because I am only the active member assigned roles necessary for approvement. This structure is come from a historical reason, but it is not practical now. I have no idea if I should approve this join request, so I always approve any join request. That is not a healthy way of community management. I suggest that each language groups should have at least two coordinators, who is responsible for overseeing a particular language within a team. For more details, see transifex documents: https://docs.transifex.com/teams/understanding-user-roles#language-coordinators If you have any comment, please let me know. Best regards, cocoatomo -- class Cocoatomo: name = 'cocoatomo' email_address = 'cocoatomo77 at gmail.com' twitter_id = '@cocoatomo' -------------- next part -------------- An HTML attachment was scrubbed... URL: From oon.arfiandwi at gmail.com Tue Oct 15 15:23:00 2019 From: oon.arfiandwi at gmail.com (oon arfiandwi) Date: Wed, 16 Oct 2019 03:23:00 +0800 Subject: [Doc-SIG] Python Documentation Translation to Bahasa Indonesia (Indonesian Language) In-Reply-To: References: Message-ID: Hi Julien, it's so cool, thank you! On Tue, Oct 15, 2019 at 9:32 PM Julien Palard wrote: > o/ > > Done: https://github.com/python/python-docs-id/ > > got it. and I have successfully push commit there. \o/ > > You can run a test build locally, like the README says (read the > docsbuild-script README there's some important mkdir and venv setup) but > adding a --language and a --branch: > > python3 ./build_docs.py --quick --build-root build_root --www-root www > --log-directory logs --group $(id -g) --skip-cache-invalidation --branch > 3.8 --languages id > > The you can browse the doc using: > > python3 -m http.server -d www/ > > Tell me how it goes. > I will back to you soon with this report. currently, a few hundreds more texts from the tutorial directory, and then build the docs. -- sincerely, oon arfiandwi -------------- next part -------------- An HTML attachment was scrubbed... URL: From oon.arfiandwi at gmail.com Tue Oct 15 15:34:22 2019 From: oon.arfiandwi at gmail.com (oon arfiandwi) Date: Wed, 16 Oct 2019 03:34:22 +0800 Subject: [Doc-SIG] Looking for language coordinators In-Reply-To: References: Message-ID: Hi cocoatomo, yes.. congratulations for all members and community, finally release Python 3.8. Related to Transifex, I think I can join you as Coordinator for the Indonesian Language, I will help to approve (or reject?) new members, invite or add reviewer (if any). Because currently we still use Transifex as our main tools. what else can I do to support a better community in Transifex? thank you. -- sincerely, oon arfiandwi On Wed, Oct 16, 2019 at 12:07 AM tomo cocoa wrote: > Hello, all translators > > First of all, I like to celebrate the GA release of Python 3.8 and > congratulate all members related to this release!! > > I send this email, because I want to share roles on the Transifex project. > Currently, all join requests and adding languages requests are approved by > me, > because I am only the active member assigned roles necessary for > approvement. > > This structure is come from a historical reason, but it is not practical > now. > I have no idea if I should approve this join request, so I always approve > any join request. > That is not a healthy way of community management. > > I suggest that each language groups should have at least two coordinators, > who is responsible for overseeing a particular language within a team. > For more details, see transifex documents: > https://docs.transifex.com/teams/understanding-user-roles#language-coordinators > > If you have any comment, please let me know. > > Best regards, > cocoatomo > > -- > class Cocoatomo: > name = 'cocoatomo' > email_address = 'cocoatomo77 at gmail.com' > twitter_id = '@cocoatomo' > _______________________________________________ > Doc-SIG maillist - Doc-SIG at python.org > https://mail.python.org/mailman/listinfo/doc-sig > -------------- next part -------------- An HTML attachment was scrubbed... URL: From julien at palard.fr Tue Oct 15 15:43:08 2019 From: julien at palard.fr (Julien Palard) Date: Tue, 15 Oct 2019 19:43:08 +0000 Subject: [Doc-SIG] Looking for language coordinators In-Reply-To: References: Message-ID: Hi cocoatomo, > I want to share roles on the Transifex project. I don't really know Transifex, as we're no longer using it since a few years for french translation. Is it possible to just drop fr from Transifex? Bests, --? Julien Palard https://mdk.fr From oon.arfiandwi at gmail.com Thu Oct 17 12:00:50 2019 From: oon.arfiandwi at gmail.com (oon arfiandwi) Date: Fri, 18 Oct 2019 00:00:50 +0800 Subject: [Doc-SIG] Python Documentation Translation to Bahasa Indonesia (Indonesian Language) In-Reply-To: References: Message-ID: Hi Julien, hope this email finds you well. I have finished (committed) all files as required by PEP 545. Currently, I browse the documentation locally, while looking for minor update related to the translation. My next plan would be adding PR to docsbuild-scripts on this weekend. oh, the step to build local docs below is almost perfect, just one additional edit of the build_docs.py related to "LANGUAGES" and " SPHINXOPTS". and all built perfectly. thank you. >> You can run a test build locally, like the README says (read the >> docsbuild-script README there's some important mkdir and venv setup) but >> adding a --language and a --branch: >> >> python3 ./build_docs.py --quick --build-root build_root --www-root >> www --log-directory logs --group $(id -g) --skip-cache-invalidation >> --branch 3.8 --languages id >> >> The you can browse the doc using: >> >> python3 -m http.server -d www/ >> >> Tell me how it goes. >> > > -- sincerely, oon arfiandwi -------------- next part -------------- An HTML attachment was scrubbed... URL: From cocoatomo77 at gmail.com Fri Oct 18 12:32:44 2019 From: cocoatomo77 at gmail.com (tomo cocoa) Date: Sat, 19 Oct 2019 01:32:44 +0900 Subject: [Doc-SIG] Looking for language coordinators In-Reply-To: References: Message-ID: Hi oon, Thank you for reply, and I feel happy. I sent a email to invite you to Indonesian coordinator just now. Please check your mailbox. > what else can I do to support a better community in Transifex? Currently, I have no burden except joining requests. Thank you very much! Sincerely yours, cocoatomo On Wed, 16 Oct 2019 at 04:34, oon arfiandwi wrote: > > Hi cocoatomo, > > yes.. congratulations for all members and community, finally release > Python 3.8. > > Related to Transifex, I think I can join you as Coordinator for the > Indonesian Language, > I will help to approve (or reject?) new members, invite or add reviewer > (if any). > Because currently we still use Transifex as our main tools. > > what else can I do to support a better community in Transifex? > > thank you. > > -- > sincerely, > oon arfiandwi > > > On Wed, Oct 16, 2019 at 12:07 AM tomo cocoa wrote: > >> Hello, all translators >> >> First of all, I like to celebrate the GA release of Python 3.8 and >> congratulate all members related to this release!! >> >> I send this email, because I want to share roles on the Transifex project. >> Currently, all join requests and adding languages requests are approved >> by me, >> because I am only the active member assigned roles necessary for >> approvement. >> >> This structure is come from a historical reason, but it is not practical >> now. >> I have no idea if I should approve this join request, so I always approve >> any join request. >> That is not a healthy way of community management. >> >> I suggest that each language groups should have at least two coordinators, >> who is responsible for overseeing a particular language within a team. >> For more details, see transifex documents: >> https://docs.transifex.com/teams/understanding-user-roles#language-coordinators >> >> If you have any comment, please let me know. >> >> Best regards, >> cocoatomo >> >> -- >> class Cocoatomo: >> name = 'cocoatomo' >> email_address = 'cocoatomo77 at gmail.com' >> twitter_id = '@cocoatomo' >> _______________________________________________ >> Doc-SIG maillist - Doc-SIG at python.org >> https://mail.python.org/mailman/listinfo/doc-sig >> > -- class Cocoatomo: name = 'cocoatomo' email_address = 'cocoatomo77 at gmail.com' twitter_id = '@cocoatomo' -------------- next part -------------- An HTML attachment was scrubbed... URL: From cocoatomo77 at gmail.com Fri Oct 18 12:55:10 2019 From: cocoatomo77 at gmail.com (tomo cocoa) Date: Sat, 19 Oct 2019 01:55:10 +0900 Subject: [Doc-SIG] Looking for language coordinators In-Reply-To: References: Message-ID: Hi Julien, Of course, your team members not need to do anything if coordinator role is not necessary. > Is it possible to just drop fr from Transifex? Does the word "drop" mean delete the fr team from Transifex projects of organization Python document translations? Best Regards, cocoatomo On Wed, 16 Oct 2019 at 04:43, Julien Palard wrote: > Hi cocoatomo, > > > I want to share roles on the Transifex project. > > I don't really know Transifex, as we're no longer using it since a few > years for french translation. Is it possible to just drop fr from Transifex? > > Bests, > -- > Julien Palard > https://mdk.fr > > -- class Cocoatomo: name = 'cocoatomo' email_address = 'cocoatomo77 at gmail.com' twitter_id = '@cocoatomo' -------------- next part -------------- An HTML attachment was scrubbed... URL: From julien at palard.fr Sat Oct 19 10:45:39 2019 From: julien at palard.fr (Julien Palard) Date: Sat, 19 Oct 2019 14:45:39 +0000 Subject: [Doc-SIG] Looking for language coordinators In-Reply-To: References: Message-ID: o/ > Does the word "drop" mean delete the fr team from Transifex projects of organization Python document translations? Yes, if possibe. We stoped "tx pull"ing a long time ago. We're still pulling like twice a year "just in case" but there's nothing. So I thinkg it's better to just close it so nobody will "get lost there". Bests, --? Julien Palard https://mdk.fr From cocoatomo77 at gmail.com Sat Oct 19 11:56:58 2019 From: cocoatomo77 at gmail.com (tomo cocoa) Date: Sun, 20 Oct 2019 00:56:58 +0900 Subject: [Doc-SIG] Looking for language coordinators In-Reply-To: References: Message-ID: Yes, I agree. I deleted all translators and coordinator from the fr team (the team originally has no reviewers). Additionally, I remove French languages from all not archived project (such as Python, Python 3.7, etc). ref. https://docs.transifex.com/teams/deleting-translation-teams Please let me know if additional work is needed. Thank you. On Sat, 19 Oct 2019 at 23:45, Julien Palard wrote: > o/ > > > Does the word "drop" mean delete the fr team from Transifex projects of > organization Python document translations? > > Yes, if possibe. We stoped "tx pull"ing a long time ago. We're still > pulling like twice a year "just in case" but there's nothing. So I thinkg > it's better to just close it so nobody will "get lost there". > > Bests, > -- > Julien Palard > https://mdk.fr > > -- class Cocoatomo: name = 'cocoatomo' email_address = 'cocoatomo77 at gmail.com' twitter_id = '@cocoatomo' -------------- next part -------------- An HTML attachment was scrubbed... URL: From oon.arfiandwi at gmail.com Sat Oct 19 12:29:58 2019 From: oon.arfiandwi at gmail.com (oon arfiandwi) Date: Sun, 20 Oct 2019 00:29:58 +0800 Subject: [Doc-SIG] Looking for language coordinators In-Reply-To: References: Message-ID: Hi cocoatomo, I have received your invitation as Coordinator of the Indonesian Language Team. Thank you, will learn about the role later. currently, I got a message on Transifex that I need to "sign" document on https://www.python.org/psf/contrib/contrib-form/ with bugs.python.org account. is it related to my new role as Coordinator, or this is a new requirement that do all translators have to sign that form? do you have information about that? thank you. -- sincerely, oon arfiandwi On Sat, Oct 19, 2019 at 12:32 AM tomo cocoa wrote: > Hi oon, > > Thank you for reply, and I feel happy. > I sent a email to invite you to Indonesian coordinator just now. > Please check your mailbox. > > -------------- next part -------------- An HTML attachment was scrubbed... URL: From cocoatomo77 at gmail.com Sat Oct 19 13:37:50 2019 From: cocoatomo77 at gmail.com (tomo cocoa) Date: Sun, 20 Oct 2019 02:37:50 +0900 Subject: [Doc-SIG] Looking for language coordinators In-Reply-To: References: Message-ID: Hi oon, I think the "sign" is related to coordinator role, but not perfectly sure. This "signing" rule would come from PEP 545, which authors are Julien, Naoki and Victor, so please ask Julien for details. On Sun, 20 Oct 2019 at 01:30, oon arfiandwi wrote: > > Hi cocoatomo, > > I have received your invitation as Coordinator of the Indonesian Language > Team. > Thank you, will learn about the role later. > > currently, I got a message on Transifex that I need to "sign" document on > https://www.python.org/psf/contrib/contrib-form/ > with bugs.python.org account. > > is it related to my new role as Coordinator, or this is a new requirement > that > do all translators have to sign that form? > > do you have information about that? > > thank you. > > -- > sincerely, > oon arfiandwi > > > > On Sat, Oct 19, 2019 at 12:32 AM tomo cocoa wrote: > >> Hi oon, >> >> Thank you for reply, and I feel happy. >> I sent a email to invite you to Indonesian coordinator just now. >> Please check your mailbox. >> >> -- class Cocoatomo: name = 'cocoatomo' email_address = 'cocoatomo77 at gmail.com' twitter_id = '@cocoatomo' -------------- next part -------------- An HTML attachment was scrubbed... URL: From julien at palard.fr Sun Oct 20 09:42:10 2019 From: julien at palard.fr (Julien Palard) Date: Sun, 20 Oct 2019 13:42:10 +0000 Subject: [Doc-SIG] Looking for language coordinators In-Reply-To: References: Message-ID: Hi! > I think the "sign" is related to coordinator role, but not perfectly sure. > This "signing" rule would come from PEP 545, which authors are Julien, Naoki and Victor, > so please ask Julien for details. To clarify, coordinator as seen by Transifex and coordinator as seen by PEP 545 are not strictly equivalent : - PEP 545 is tool agnostic, so a coordinator for PEP 545 is the obvious person to ask any question about a given translation, either from local translator point of view or from the core team / psf point of view. - Transifex Coordinator is ... I don't know in fact, but I bet it's documented in transfiex documentation. I bet being the PEP 545 coordinator for a language that uses transifex mostly implies that the same person should be coordinator on transifex, or could delegate the task to someone else. About the PSF CLA signing, IANAL but: - Simply translating does not require CLA signing thanks to the paragraph (from PEP 545) every translation put in their README clearly indicating that all the works is in CC0. - Producing more that just translations (PR against docsbuild-scripts, cpython, psf-salt, or any repo in github.com/python/, linked to the translation or not) requires the CLA to be signed and is enforced by a bot. - Helping a community (like being a PEP545 coordinator, a transfiex coordinator, organizing meetups, and so on) don't require CLA signing. In any cases, or in doubt, I'd say sign it now, so if you need to push something in a python related repo in the future, you won't be slowed down with the signing process. Bests, --? Julien Palard https://mdk.fr From oon.arfiandwi at gmail.com Sun Oct 20 11:58:15 2019 From: oon.arfiandwi at gmail.com (oon arfiandwi) Date: Sun, 20 Oct 2019 23:58:15 +0800 Subject: [Doc-SIG] Python Documentation Translation to Bahasa Indonesia (Indonesian Language) In-Reply-To: References: Message-ID: Hi Julien, hope this email finds you well. I have built and tested the documentation in Indonesian with some friends, it looks ok. We still have quite a lot of homework to do, including to fully translate the Spinx, because some of the generated output still in English. On Tue, Oct 15, 2019 at 6:15 AM Julien Palard wrote: > > > d. and what to do next, if I have completed the translations (a), to be > included on language switcher? > > Once the repository migrated, open a PR to add your language here: > https://github.com/python/docsbuild-scripts/blob/master/build_docs.py#L62 > > I propose the next step to build the documentation on docs.python.org server, to gather more persons to help us translate the documentation. So, I created a PR #80 https://github.com/python/docsbuild-scripts/pull/80 would you please merge it? and for the "language switcher", I will create another email in the next few weeks, to make sure that the coverage of the contents is quite good. thank you. -- sincerely, oon arfiandwi -------------- next part -------------- An HTML attachment was scrubbed... URL: From oon.arfiandwi at gmail.com Sun Oct 20 12:05:13 2019 From: oon.arfiandwi at gmail.com (oon arfiandwi) Date: Mon, 21 Oct 2019 00:05:13 +0800 Subject: [Doc-SIG] Looking for language coordinators In-Reply-To: References: Message-ID: Dear Julien and cocoatomo, thank you for the clear explanation. On Sun, Oct 20, 2019 at 9:42 PM Julien Palard wrote: > > About the PSF CLA signing, IANAL but: > - Simply translating does not require CLA signing thanks to the paragraph > (from PEP 545) every translation put in their README clearly indicating > that all the works is in CC0. > - Producing more that just translations (PR against docsbuild-scripts, > cpython, psf-salt, or any repo in github.com/python/, linked to the > translation or not) requires the CLA to be signed and is enforced by a bot. > - Helping a community (like being a PEP545 coordinator, a transfiex > coordinator, organizing meetups, and so on) don't require CLA signing. > > yes, that is my most concern actually. I don't need to ask other people to sign the CLA, just to get translation help from them. > In any cases, or in doubt, I'd say sign it now, so if you need to push > something in a python related repo in the future, you won't be slowed down > with the signing process. > > and yes, I have signed the CLA. also create an account on bugs.python.org for any further purpose related to the translation of Python documentation. -- sincerely, oon arfiandwi -------------- next part -------------- An HTML attachment was scrubbed... URL: From zsj950618 at gmail.com Wed Oct 23 11:47:19 2019 From: zsj950618 at gmail.com (Shengjing Zhu) Date: Wed, 23 Oct 2019 23:47:19 +0800 Subject: [Doc-SIG] PSF CLA is enforced on Transifex project In-Reply-To: References: Message-ID: Hi cocoatomo, > About the PSF CLA signing, IANAL but: > - Simply translating does not require CLA signing thanks to the paragraph (from PEP 545) every translation put in their README clearly indicating that all the works is in CC0. > - Producing more that just translations (PR against docsbuild-scripts, cpython, psf-salt, or any repo in github.com/python/, linked to the translation or not) requires the CLA to be signed and is enforced by a bot. > - Helping a community (like being a PEP545 coordinator, a transfiex coordinator, organizing meetups, and so on) don't require CLA signing. I now see on Transifex that, "In order to contribute to or use translations of this project, you must agree to its Contributor's License Agreement (CLA)" Translators need to agree the PSF CLA. This is not needed. PEP545 also doesn't say that. The PEP says, translators need to agree the "Documentation Contribution Agreement". It's different from the PSF CLA[1]. BTW, the PEP says the "Documentation Contribution Agreement" should have its own page. But it's still not available, @mdk do you plan to set it up? [1] https://www.python.org/psf/contrib/contrib-form/ -- Regards, Shengjing Zhu From julien at palard.fr Wed Oct 23 12:42:46 2019 From: julien at palard.fr (Julien Palard) Date: Wed, 23 Oct 2019 16:42:46 +0000 Subject: [Doc-SIG] PSF CLA is enforced on Transifex project In-Reply-To: References: Message-ID: Hi! > I now see on Transifex that, > > "In order to contribute to or use translations of this project, you > must agree to its Contributor's License Agreement (CLA)" This text should be changed with: NOTE REGARDING THE LICENSE FOR TRANSLATIONS: Python's documentation is maintained using a global network of volunteers. By posting this project on Transifex, GitHub, and other public places, and inviting you to participate, we are proposing an agreement that you will provide your improvements to Python's documentation or the translation of Python's documentation for the PSF's use under the CC0 license (available at `https://creativecommons.org/publicdomain/zero/1.0/legalcode`_). In return, you may publicly claim credit for the portion of the translation you contributed and if your translation is accepted by the PSF, you may (but are not required to) submit a patch including an appropriate annotation in the Misc/ACKS or TRANSLATORS file. Although nothing in this Documentation Contribution Agreement obligates the PSF to incorporate your textual contribution, your participation in the Python community is welcomed and appreciated. You signify acceptance of this agreement by submitting your work to the PSF for inclusion in the documentation. > BTW, the PEP says the "Documentation Contribution Agreement" should > have its own page. But it's still not available, @mdk do you plan to > set it up? The Documentation Contribution Agreement needs to be clearly displayed to contributor, by any mean. (Own page, popup on transifex, README, whatever as long as contributor see it). --? Julien Palard https://mdk.fr From zsj950618 at gmail.com Wed Oct 23 13:48:47 2019 From: zsj950618 at gmail.com (Shengjing Zhu) Date: Thu, 24 Oct 2019 01:48:47 +0800 Subject: [Doc-SIG] PSF CLA is enforced on Transifex project In-Reply-To: References: Message-ID: On Thu, Oct 24, 2019 at 12:42 AM Julien Palard wrote: > > BTW, the PEP says the "Documentation Contribution Agreement" should > > have its own page. But it's still not available, @mdk do you plan to > > set it up? > > The Documentation Contribution Agreement needs to be clearly > displayed to contributor, by any mean. (Own page, popup on transifex, > README, whatever as long as contributor see it). > I think a web page is still needed, on python.org like https://www.python.org/psf/contrib/doc-contrib-form/ So you can link it from elsewhere. -- Regards, Shengjing Zhu From julien at palard.fr Wed Oct 23 16:20:00 2019 From: julien at palard.fr (Julien Palard) Date: Wed, 23 Oct 2019 20:20:00 +0000 Subject: [Doc-SIG] PSF CLA is enforced on Transifex project In-Reply-To: References: Message-ID: > I think a web page is still needed, on python.org It's available on PEP 545, which is also linked from https://devguide.python.org/documenting/#translating. Why would you need it elsewhere? As I understand it, it has to be displayed to users, not linked to. --? Julien Palard https://mdk.fr From abckristinaa at gmail.com Mon Oct 28 05:57:42 2019 From: abckristinaa at gmail.com (Kristina Mironova) Date: Mon, 28 Oct 2019 12:57:42 +0300 Subject: [Doc-SIG] Looking for language coordinators (Russian) Message-ID: Hi, Tomo! I will be glad to be a coordinator for the Russian Language Team. As we translate documentation on transifex it's always a question for new participants whether they requests be approved or not and when. It will be more convenient to approve the join requests from our new translators within a Team. Absolutely support your idea to share the roles. Best regards, Kristina Mironova -------------- next part -------------- An HTML attachment was scrubbed... URL: From cocoatomo77 at gmail.com Mon Oct 28 20:31:53 2019 From: cocoatomo77 at gmail.com (tomo cocoa) Date: Tue, 29 Oct 2019 09:31:53 +0900 Subject: [Doc-SIG] Looking for language coordinators (Russian) In-Reply-To: References: Message-ID: Hi, Kristina! Thank you for the support of translation management. I sent an invitation to you to promote you to coordinator. Please check your mailbox ro Transifex notification. BTW, Transifex project also has the Russian (Russia) team. How is this team related to the Russian team? Do you want to be a coordinator of the Russian (Russia) team? Thank you! Best regards, cocoatomo On Mon, 28 Oct 2019 at 18:57, Kristina Mironova wrote: > Hi, Tomo! > > I will be glad to be a coordinator for the Russian Language Team. > As we translate documentation on transifex it's always a question for new > participants whether they requests be approved or not and when. > It will be more convenient to approve the join requests from our new > translators within a Team. > > Absolutely support your idea to share the roles. > > > Best regards, > Kristina Mironova > -- class Cocoatomo: name = 'cocoatomo' email_address = 'cocoatomo77 at gmail.com' twitter_id = '@cocoatomo' -------------- next part -------------- An HTML attachment was scrubbed... URL: From abckristinaa at gmail.com Tue Oct 29 03:17:50 2019 From: abckristinaa at gmail.com (Kristina Mironova) Date: Tue, 29 Oct 2019 10:17:50 +0300 Subject: [Doc-SIG] Looking for language coordinators (Russian) In-Reply-To: References: Message-ID: Hi, Tomo! Thanks for the invitation. To the question about Russian(Russia) - we have only one team and only one language. If I checked it correctly - this branch of language doesn't contain any translations, maybe it would be better to delete it at all to avoid confusion. Best regards, Kristina Mironova ??, 29 ???. 2019 ?. ? 03:32, tomo cocoa : > Hi, Kristina! > > Thank you for the support of translation management. > I sent an invitation to you to promote you to coordinator. > Please check your mailbox ro Transifex notification. > > BTW, Transifex project also has the Russian (Russia) team. > How is this team related to the Russian team? > Do you want to be a coordinator of the Russian (Russia) team? > > Thank you! > > Best regards, > cocoatomo > > On Mon, 28 Oct 2019 at 18:57, Kristina Mironova > wrote: > >> Hi, Tomo! >> >> I will be glad to be a coordinator for the Russian Language Team. >> As we translate documentation on transifex it's always a question for new >> participants whether they requests be approved or not and when. >> It will be more convenient to approve the join requests from our new >> translators within a Team. >> >> Absolutely support your idea to share the roles. >> >> >> Best regards, >> Kristina Mironova >> > > > -- > class Cocoatomo: > name = 'cocoatomo' > email_address = 'cocoatomo77 at gmail.com' > twitter_id = '@cocoatomo' > -------------- next part -------------- An HTML attachment was scrubbed... URL: