From julien at palard.fr  Sun Dec  1 16:37:41 2019
From: julien at palard.fr (Julien Palard)
Date: Sun, 01 Dec 2019 21:37:41 +0000
Subject: [Doc-SIG] Adjustment of toctree depth
In-Reply-To: <CAN_7T0KbwXNEerU8ZaHLYh5GT=FH=TDNq0aCO3VEEOjLQm65dg@mail.gmail.com>
References: <CAN_7T0KbwXNEerU8ZaHLYh5GT=FH=TDNq0aCO3VEEOjLQm65dg@mail.gmail.com>
Message-ID: <4M2aMs327NsSarIdRl6S9GRkFkUHMH4w-4kFTbIJBjRbLgB0W6N5WVr_nZWC_eSHtAVEkkYa76QGZWkYlDmcEPrjZaguZK6jUYdJ1XD_OcA=@palard.fr>

Hi!

> Since Python documentation is hard to grasp items listed on index pages,
> only items located at top and second level in toctree would be shown
> in order to mitigate burden of reading the documentation.

I don't have a personal idea of what's good what's not about those. And I bet you won't have much feedback on doc-sig those days but I may be wrong (proove me wrong, you all).

Maybe ask on python-ideas and run a twitter poll?

Bests,
--?
Julien Palard
https://mdk.fr


From mariatta.wijaya at gmail.com  Thu Dec  5 16:15:30 2019
From: mariatta.wijaya at gmail.com (Mariatta)
Date: Thu, 5 Dec 2019 13:15:30 -0800
Subject: [Doc-SIG] Looking for Translation Help for PyLadies
Message-ID: <CAGbohnYCPaW8PX+0g41AR8oCOufZa0bRZE1REvTi+5mc3tvJTg@mail.gmail.com>

Hello,

We are looking for volunteers to help us translate the proposal: ?PyLadies
Global Council Selection Process? into one of the 6 official languages of
the UN, which are: Arabic, French, English, Russian, Spanish, and Mandarin
Chinese . The text for it can be found at
https://github.com/pyladies/global-organizing/issues/32#issue-509308891

The proposal will affect how PyLadies will be governed in the future, and
we are actively seeking input and feedback from our community members.
However, we realized that our community is global; we recognized the need
to have the proposal translated in order to include the diverse voices of
PyLadies community members around the world.

Within our own community, we?ve had members starting to translate the text
into Spanish (by Tania Allard, Lorena Mesa, and Gisela Rosi) and Portuguese
(by Debora Azevedo). We still need help with translating to Arabic, French,
Russian, and Mandarin Chinese, ideally by December 15.

If any of you are able to help, or know someone who could help us, please
let me know.


I do realize that this might be out of scope of the docs-sig workgroup, so
thank you in advance for the consideration and willingness to help PyLadies
community.

Thanks

Mariatta on behalf of PyLadies
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/doc-sig/attachments/20191205/ced90cbd/attachment.html>

From maciej.olko at gmail.com  Tue Dec 10 16:49:31 2019
From: maciej.olko at gmail.com (Maciek Olko)
Date: Tue, 10 Dec 2019 22:49:31 +0100
Subject: [Doc-SIG] Looking for language coordinators
In-Reply-To: <CAN_7T0LG0yUJDE=dqvYNKFr+iskbh1jTXP09QnVPVh4vKtA6ew@mail.gmail.com>
References: <CAN_7T0LG0yUJDE=dqvYNKFr+iskbh1jTXP09QnVPVh4vKtA6ew@mail.gmail.com>
Message-ID: <CALYYG82hDCy0BKWP-4Axn=uWmFYnoV-DH9RJCS6CRyiegZYo_w@mail.gmail.com>

Hello cocoatomo,

I'll be happy to become Transifex coordinator of Polish team. I am on
Transifex as m_aciek [1].

Kind regards,
Maciej

[1] https://www.transifex.com/user/profile/m_aciek/

wt., 15 pa? 2019 o 18:07 tomo cocoa <cocoatomo77 at gmail.com> napisa?(a):

> 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: <http://mail.python.org/pipermail/doc-sig/attachments/20191210/a6cd2687/attachment.html>

From cocoatomo77 at gmail.com  Tue Dec 10 20:09:07 2019
From: cocoatomo77 at gmail.com (tomo cocoa)
Date: Wed, 11 Dec 2019 10:09:07 +0900
Subject: [Doc-SIG] Looking for language coordinators
In-Reply-To: <CALYYG82hDCy0BKWP-4Axn=uWmFYnoV-DH9RJCS6CRyiegZYo_w@mail.gmail.com>
References: <CAN_7T0LG0yUJDE=dqvYNKFr+iskbh1jTXP09QnVPVh4vKtA6ew@mail.gmail.com>
 <CALYYG82hDCy0BKWP-4Axn=uWmFYnoV-DH9RJCS6CRyiegZYo_w@mail.gmail.com>
Message-ID: <CAN_7T0+M2RP+3RD-5Nf-wVDSicDr63mrKOoJDLUK1o+w7Z4mqg@mail.gmail.com>

Hello Maciek,

Thank you for the offer!!
I promoted you to a language coordinator of the Polish team.

I hope it will be a fruitful translation work for the team.

Kind regards,
tomo


On Wed, 11 Dec 2019 at 06:49, Maciek Olko <maciej.olko at gmail.com> wrote:

> Hello cocoatomo,
>
> I'll be happy to become Transifex coordinator of Polish team. I am on
> Transifex as m_aciek [1].
>
> Kind regards,
> Maciej
>
> [1] https://www.transifex.com/user/profile/m_aciek/
>
> wt., 15 pa? 2019 o 18:07 tomo cocoa <cocoatomo77 at gmail.com> napisa?(a):
>
>> 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: <http://mail.python.org/pipermail/doc-sig/attachments/20191211/d94fc0d5/attachment.html>

From eiro at phear.org  Fri Dec 20 13:55:23 2019
From: eiro at phear.org (Marc Chantreux)
Date: Fri, 20 Dec 2019 19:55:23 +0100
Subject: [Doc-SIG] a better path from error message to solution
Message-ID: <20191220185523.GA3237@prometheus.u-strasbg.fr>

hello people,

i try to educate my children to have a reasonable use of digital
ressources so they try to respect 2 rules:

* don't use a search engine if you don't need
* don't use the bandwith to get something you already have on
  your machine

my kid use python at school and get stuck on very basic errors like
TypeError. I realize how difficult it is for a non programmer to make
the connexion between the error message and the relevant doc.

so: those are ideas i would like to share with your as a perl monger
who miss the perl ecosystem when writting python code:

* don't stacktrace by default: backtraces are just noise for newbies.
* make the messages a little bit informative. maybe with links to the
  documentation.
* have a python module that behaves like perl diagnostics (https://metacpan.org/pod/distribution/perl/lib/diagnostics.pm) at least as a ipython extension.
* make pydoc able to show the doc related to an Error
* make the official documentation available with man (the way perl does
  it: man perl gives you the list of other man pages that are both
  turorials and reference).
* have the error messages translated into natural langages

hope that helps.
regards,
marc




From oon.arfiandwi at gmail.com  Mon Dec 23 12:25:33 2019
From: oon.arfiandwi at gmail.com (oon arfiandwi)
Date: Tue, 24 Dec 2019 01:25:33 +0800
Subject: [Doc-SIG] Python Documentation Translation to Bahasa Indonesia
 (Indonesian Language)
In-Reply-To: <CACUNLpXRqm-m7-oE=DPCbq+j0Q1B3FuBY1P7TVN2y74Cw7dDPw@mail.gmail.com>
References: <CACUNLpUjv+RRFb-9TX4uK9QYfkuFyiZPqkqAf9VM_85pK8og6g@mail.gmail.com>
 <K7Ud-asXDvZSg5LLWBDM0ktniYRcRX0uO8m-OwPWIMRENi_B3G-O4bmOd9Uqrjx-U_eFNHuoFEaRCLB6thyJAv0uJiOBaWumVj-R55Fn3GU=@palard.fr>
 <CACUNLpXRqm-m7-oE=DPCbq+j0Q1B3FuBY1P7TVN2y74Cw7dDPw@mail.gmail.com>
Message-ID: <CACUNLpWECZEO=uOsUZv1DHUGG0D3gqnMqK2FbVWdfkWiO8O2TQ@mail.gmail.com>

Dear Julien,
I hope this email finds you well.
happy holiday of all of you on the mailing list.

After waiting for about a month now,
Our translation at Sphinx has been integrated into version 2.3 (yesterday
they release version 2.3.1).

I saw your latest PR related to my concern:
https://github.com/python/docsbuild-scripts/pull/81

Currently, on https://docs.python.org/id/3.8/
I saw "Created using Sphinx 2.2.1".

Would you please give me guidance on what to do to have
documentation for language "id" branch "3.8" built using Sphinx "2.3.1"?

not in a rush, just let me know after the holiday would be ok.

thank you for your support!

-- 
sincerely,
oon arfiandwi
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/doc-sig/attachments/20191224/90bfd4c5/attachment.html>

From julien at palard.fr  Mon Dec 23 16:36:15 2019
From: julien at palard.fr (Julien Palard)
Date: Mon, 23 Dec 2019 21:36:15 +0000
Subject: [Doc-SIG] Python Documentation Translation to Bahasa Indonesia
 (Indonesian Language)
In-Reply-To: <CAGbohnZKwzqX78q4eKLS0+8GhC4zhQv9vBmrVHgryFawB=BBEw@mail.gmail.com>
References: <CACUNLpUjv+RRFb-9TX4uK9QYfkuFyiZPqkqAf9VM_85pK8og6g@mail.gmail.com>
 <K7Ud-asXDvZSg5LLWBDM0ktniYRcRX0uO8m-OwPWIMRENi_B3G-O4bmOd9Uqrjx-U_eFNHuoFEaRCLB6thyJAv0uJiOBaWumVj-R55Fn3GU=@palard.fr>
 <CACUNLpXRqm-m7-oE=DPCbq+j0Q1B3FuBY1P7TVN2y74Cw7dDPw@mail.gmail.com>
 <CACUNLpWECZEO=uOsUZv1DHUGG0D3gqnMqK2FbVWdfkWiO8O2TQ@mail.gmail.com>
 <CAGbohnZKwzqX78q4eKLS0+8GhC4zhQv9vBmrVHgryFawB=BBEw@mail.gmail.com>
Message-ID: <iXBOyTwToEnt-Al2XHs99jANonm_99ApUWxZpO4IUvQa732vkxPj4V2RZqRwKWiS_9G457qfJOlgaUL-AInvmj_F1oYP9gE_cs2Al0mgkhU=@palard.fr>

o/

> I think you would need to update the requirements.txt file to use sphinx==2.3.1
>
> https://github.com/python/docsbuild-scripts/blob/ca26cd4c28f70f3b88c2547509892087cfad18ac/requirements.txt#L26

Yes, but don't worry, I'll take care of it (or someone accustomed to it will), as it will bump sphinx for all languages and all branch at the same time, I have to test everything before bumping.

> > Would you please give me guidance on what to do to have
> > documentation for language "id" branch "3.8" built using Sphinx "2.3.1"?

Reading you, I feel like your translation *needs* Sphinx 2.3.1, is there any feature from 2.3.1 you need you don't have in 2.2.1? If so I can try to bump soon. If you don't really care about which Sphinx version is used, I'll bump *sometime* (as it takes time to double check everything, I'm not trying to follow upstream sphinx on a daily basis, I only bump from time to time or when we really need it).

Bests,
--?
Julien Palard
https://mdk.fr


From mariatta at python.org  Mon Dec 23 13:01:21 2019
From: mariatta at python.org (Mariatta)
Date: Mon, 23 Dec 2019 10:01:21 -0800
Subject: [Doc-SIG] Python Documentation Translation to Bahasa Indonesia
 (Indonesian Language)
In-Reply-To: <CACUNLpWECZEO=uOsUZv1DHUGG0D3gqnMqK2FbVWdfkWiO8O2TQ@mail.gmail.com>
References: <CACUNLpUjv+RRFb-9TX4uK9QYfkuFyiZPqkqAf9VM_85pK8og6g@mail.gmail.com>
 <K7Ud-asXDvZSg5LLWBDM0ktniYRcRX0uO8m-OwPWIMRENi_B3G-O4bmOd9Uqrjx-U_eFNHuoFEaRCLB6thyJAv0uJiOBaWumVj-R55Fn3GU=@palard.fr>
 <CACUNLpXRqm-m7-oE=DPCbq+j0Q1B3FuBY1P7TVN2y74Cw7dDPw@mail.gmail.com>
 <CACUNLpWECZEO=uOsUZv1DHUGG0D3gqnMqK2FbVWdfkWiO8O2TQ@mail.gmail.com>
Message-ID: <CAGbohnZKwzqX78q4eKLS0+8GhC4zhQv9vBmrVHgryFawB=BBEw@mail.gmail.com>

I think you would need to update the requirements.txt file to use
sphinx==2.3.1

https://github.com/python/docsbuild-scripts/blob/ca26cd4c28f70f3b88c2547509892087cfad18ac/requirements.txt#L26

On Mon, Dec 23, 2019, 9:25 AM oon arfiandwi <oon.arfiandwi at gmail.com> wrote:

>
> Dear Julien,
> I hope this email finds you well.
> happy holiday of all of you on the mailing list.
>
> After waiting for about a month now,
> Our translation at Sphinx has been integrated into version 2.3 (yesterday
> they release version 2.3.1).
>
> I saw your latest PR related to my concern:
> https://github.com/python/docsbuild-scripts/pull/81
>
> Currently, on https://docs.python.org/id/3.8/
> I saw "Created using Sphinx 2.2.1".
>
> Would you please give me guidance on what to do to have
> documentation for language "id" branch "3.8" built using Sphinx "2.3.1"?
>
> not in a rush, just let me know after the holiday would be ok.
>
> thank you for your support!
>
> --
> sincerely,
> oon arfiandwi
>
> _______________________________________________
> Doc-SIG maillist  -  Doc-SIG at python.org
> https://mail.python.org/mailman/listinfo/doc-sig
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/doc-sig/attachments/20191223/4eef7258/attachment.html>

From oon.arfiandwi at gmail.com  Tue Dec 24 00:35:20 2019
From: oon.arfiandwi at gmail.com (oon arfiandwi)
Date: Tue, 24 Dec 2019 13:35:20 +0800
Subject: [Doc-SIG] Python Documentation Translation to Bahasa Indonesia
 (Indonesian Language)
In-Reply-To: <iXBOyTwToEnt-Al2XHs99jANonm_99ApUWxZpO4IUvQa732vkxPj4V2RZqRwKWiS_9G457qfJOlgaUL-AInvmj_F1oYP9gE_cs2Al0mgkhU=@palard.fr>
References: <CACUNLpUjv+RRFb-9TX4uK9QYfkuFyiZPqkqAf9VM_85pK8og6g@mail.gmail.com>
 <K7Ud-asXDvZSg5LLWBDM0ktniYRcRX0uO8m-OwPWIMRENi_B3G-O4bmOd9Uqrjx-U_eFNHuoFEaRCLB6thyJAv0uJiOBaWumVj-R55Fn3GU=@palard.fr>
 <CACUNLpXRqm-m7-oE=DPCbq+j0Q1B3FuBY1P7TVN2y74Cw7dDPw@mail.gmail.com>
 <CACUNLpWECZEO=uOsUZv1DHUGG0D3gqnMqK2FbVWdfkWiO8O2TQ@mail.gmail.com>
 <CAGbohnZKwzqX78q4eKLS0+8GhC4zhQv9vBmrVHgryFawB=BBEw@mail.gmail.com>
 <iXBOyTwToEnt-Al2XHs99jANonm_99ApUWxZpO4IUvQa732vkxPj4V2RZqRwKWiS_9G457qfJOlgaUL-AInvmj_F1oYP9gE_cs2Al0mgkhU=@palard.fr>
Message-ID: <CACUNLpU9hBR4GAXskdjfwtdH3RQ5HVkz_NYSMHN6KM8hdu7zdg@mail.gmail.com>

Hi Julien,

On Tue, Dec 24, 2019 at 5:36 AM Julien Palard <julien at palard.fr> wrote:

>
> Reading you, I feel like your translation *needs* Sphinx 2.3.1, is there
> any feature from 2.3.1 you need you don't have in 2.2.1? If so I can try to
> bump soon. If you don't really care about which Sphinx version is used,
> I'll bump *sometime* (as it takes time to double check everything, I'm not
> trying to follow upstream sphinx on a daily basis, I only bump from time to
> time or when we really need it).
>
>
Yes, it is. We really need Sphinx 2.3+.
Previously, we have problem with "translation on Sphinx",
here's my issue on sphinx project:
https://github.com/sphinx-doc/sphinx/issues/6767

Sphinx project updated (integrated) our translation on version 2.3,
that's why we have wait for about a month.

I thought the Sphinx version is per language, that's why I have related to
your PR.
But from your explanation, as it will bump for all languages, I think I
will have to wait longer.

thank you for your efforts.
and also thank you ms Mariatta for the reference.

-- 
sincerely,
oon arfiandwi
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/doc-sig/attachments/20191224/562b9df0/attachment.html>

From julien at palard.fr  Tue Dec 24 09:17:10 2019
From: julien at palard.fr (Julien Palard)
Date: Tue, 24 Dec 2019 14:17:10 +0000
Subject: [Doc-SIG] a better path from error message to solution
In-Reply-To: <20191220185523.GA3237@prometheus.u-strasbg.fr>
References: <20191220185523.GA3237@prometheus.u-strasbg.fr>
Message-ID: <smLCTk5iWHIy-M2S8wTuKQ5VWcu67olCFImSUGgZgx-KTOKSdItkQ-OucrUZBXRfpPfKxfs27aTm96C0V4E0Pp_mnBHhyBUHaEsmeYF32gQ=@palard.fr>

Hi Marc,

> have a python module that behaves like perl diagnostics (https://metacpan.org/pod/distribution/perl/lib/diagnostics.pm) at least as a ipython extension.

I tried a POC around your idea, which would enable adding text (and links) to exception and to translate them.

It's here: https://pypi.org/project/teacher/ so you can test it:

$ pip install teacher
$ python3
>>> import teacher
>>> "a" * "b"
<stdin>:1: TypeError: can't multiply sequence by non-int of type 'str'
You tried to multiply 'a' by 'b'
which is not allowed, the sequence 'a' can only be multiplied by an integer.

It only handle this very specific exception, and does not try to translate it yet, it's really just a 32 lines of code POC.

If you think this is a good way to do it, what you could do now is to document, as issues here [1], the problems your child encontered, and what piece of information helped to solve the issue. Because TBH I did so much Python that exceptions *are* readable to me now, so it's really hard to take a step back and guess what's missing (I bet my POC does not even help to understand why "a" can't be multiplied by "b" ...) :]

[1]: https://github.com/JulienPalard/teacher/issues
--?
Julien Palard
https://mdk.fr


From maciej.olko at gmail.com  Mon Dec 30 06:31:53 2019
From: maciej.olko at gmail.com (Maciek Olko)
Date: Mon, 30 Dec 2019 12:31:53 +0100
Subject: [Doc-SIG] Automation of fetching changes from Transifex
Message-ID: <CALYYG80OPh2GOJZSxkeTFvsH6FPKVwF_g6V2j1-_=QepmsJ5KA@mail.gmail.com>

Hello,
I'd like to share Python script [1] and GitHub Action definition [2] which
fetch and update translation in python-docs-pl Git repository. It may be of
interest for Transifex-only translation flows.

manage_translations.py removes location comments from PO files to make
diffs in repo more plain.

It was inspired by similar script for Django documentation translations
made by Claude Paroz [3].

Feel free to contact me in case of any questions.

Kind regards,
Maciej

[1]
https://github.com/m-aciek/python-docs-pl/blob/3.8/manage_translations.py#L23-L41
[2]
https://github.com/m-aciek/python-docs-pl/blob/3.8/.github/workflows/update.yml#L8-L27
[3]
https://github.com/django/django-docs-translations/blob/stable/3.0.x/manage_translations.py
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/doc-sig/attachments/20191230/0c7fa061/attachment.html>

From zsj950618 at gmail.com  Mon Dec 30 09:25:48 2019
From: zsj950618 at gmail.com (Shengjing Zhu)
Date: Mon, 30 Dec 2019 22:25:48 +0800
Subject: [Doc-SIG] [Translation] Automation of fetching changes from
 Transifex
In-Reply-To: <CALYYG80OPh2GOJZSxkeTFvsH6FPKVwF_g6V2j1-_=QepmsJ5KA@mail.gmail.com>
References: <CALYYG80OPh2GOJZSxkeTFvsH6FPKVwF_g6V2j1-_=QepmsJ5KA@mail.gmail.com>
Message-ID: <CAG+qr1EaGD=Qk5bv+KOx=Y2s0EaWj6=E8a6UksDDJXwvFW+MzA@mail.gmail.com>

FWIW, we have similar configurations,

https://github.com/python/python-docs-zh-cn/blob/master/.github/workflows/python-38.yml


-- 
Regards,
Shengjing Zhu