Import: Write The Docs Paris 19.
|
@ -0,0 +1,207 @@
|
|||
# docs.python.org/fr
|
||||
|
||||
<!-- .slide: data-background="static/background.jpg" -->
|
||||
|
||||
<br/>
|
||||
|
||||
<b>Julien Palard</b>
|
||||
|
||||
<tt>WriteTheDocs Paris 2019</tt>
|
||||
|
||||
|
||||
## Julien Palard
|
||||
|
||||
- Python core dev and documentation expert
|
||||
- Python teacher and coach at:
|
||||
- Sup'Internet
|
||||
- CRI-Paris
|
||||
- Makina Corpus
|
||||
- …
|
||||
|
||||
|
||||
## History
|
||||
|
||||
![](static/french.python.png)
|
||||
|
||||
|
||||
## History
|
||||
|
||||
- Python is 28 years old,
|
||||
- its doc is written in reStructuredText,
|
||||
- compiled in HTML, PDF, epub, txt using Sphinx,
|
||||
- more than one million words,
|
||||
- daily changes.
|
||||
|
||||
Notes:
|
||||
28 years old as of 2019 (first release 1991).
|
||||
|
||||
More than "daily" for 3.7 stable: 170 commits on Doc/ over 120 days.
|
||||
|
||||
|
||||
## History
|
||||
|
||||
- 2000: Project frpython on sourceforge
|
||||
- 2001: Translating Python 2.0
|
||||
- 2007: Python Doc moves from Latex to Sphinx & rst
|
||||
- 2010: GSoC Project to add i18n to Sphinx
|
||||
- 2011: 2% translated on pottle.python.org
|
||||
- 2012: pottle dead, AFPy team migrates to github
|
||||
- 2015-12: Resurected the project, alone for one year
|
||||
- 2016-03: docs.python.org/fr/ on python-ideas.
|
||||
- 2017-03: PEP 545
|
||||
|
||||
Notes:
|
||||
|
||||
2000: Latex to Latex, scripté en Python 1.5.2 (populaire à l'époque)
|
||||
2007: Hello Sphinx, created for Python by Georg Brandl, now used by many like Linux Kernel
|
||||
2012: Few people contributed during a month, and left for two years.
|
||||
2015: Alone for one year
|
||||
|
||||
https://lists.afpy.org/mailman/private/afpy-membres/2012-September/005747.html
|
||||
http://frpython.sourceforge.net/
|
||||
|
||||
|
||||
## 2000
|
||||
|
||||
![](static/sourceforge.png)
|
||||
|
||||
Notes: https://web.archive.org/web/20010302160925/http://sourceforge.net/projects/frpython
|
||||
|
||||
|
||||
## 2001
|
||||
|
||||
![](static/2.0.png)
|
||||
|
||||
Notes: http://quentel.pierre.free.fr/python-trad/intro.html
|
||||
|
||||
|
||||
## 2012
|
||||
|
||||
![](static/pottle.png)
|
||||
|
||||
|
||||
## 2019
|
||||
|
||||
![](static/docs.python.org.png)
|
||||
|
||||
|
||||
## Progression
|
||||
|
||||
![](static/fr_translation_percent.png)
|
||||
|
||||
Notes:
|
||||
- 2016 jan: very short untranslatable strings
|
||||
- 2016 june: autofill whatsnew.po
|
||||
- 2017: PEP 545
|
||||
|
||||
# How do we work?
|
||||
|
||||
Mandatory meet point is:
|
||||
|
||||
`github.com/python/python-docs-*`
|
||||
|
||||
But every language can use their own tools as long as they push on the meet point.
|
||||
|
||||
|
||||
## How do we work?
|
||||
|
||||
- Some are using Transifex (ja, zh, pt_BR, ko, ...)
|
||||
- Some are using git (fr, it, es)
|
||||
- One could use any other tool…
|
||||
|
||||
Notes:
|
||||
The french fries team (fr,it,es) is using git.
|
||||
|
||||
|
||||
## How do we work, in France?
|
||||
|
||||
github and pull requests
|
||||
|
||||
![](static/prs.png)
|
||||
|
||||
----
|
||||
|
||||
## How do we work, in France?
|
||||
|
||||
It allows us to review and give feedback
|
||||
|
||||
![](static/support.png)
|
||||
|
||||
----
|
||||
|
||||
## But git is hard!
|
||||
|
||||
Yes.
|
||||
|
||||
Note: But it looks like it's the mandatory way to contribute to most
|
||||
open source projects. We want to make the translation a way to learn
|
||||
how to contribute to an open source project. It's like a git sandbox :)
|
||||
|
||||
Also it allows offline work that a lot of us do (in the train).
|
||||
|
||||
|
||||
# Tools
|
||||
|
||||
How do we cope with:
|
||||
|
||||
- Around 500 ``.po`` files,
|
||||
- more than one million words,
|
||||
- 45k paragraphs,
|
||||
- french in reStructuredText in gettext imbrication?
|
||||
|
||||
```
|
||||
#: ../Doc/library/stdtypes.rst:373
|
||||
msgid "the greatest :class:`~numbers.Integral` <= *x*"
|
||||
msgstr "le plus grand :class:`~numbers.Integral` <= *x*"
|
||||
```
|
||||
|
||||
## Tools
|
||||
|
||||
### pypi.org/p/pospell
|
||||
|
||||
``pospell`` is a tool using hunspell to spell check inside a
|
||||
``.po`` file while ignoring reStructuredText syntax.
|
||||
|
||||
|
||||
## Tools
|
||||
|
||||
### pypi.org/p/powrap
|
||||
|
||||
``powrap`` is a tool using ``msgcat`` to rewrap all ``.po`` files to a
|
||||
fixed width of 79 columns. We're enforcing this wrapping via the CI to
|
||||
reduce the noise in git logs.
|
||||
|
||||
|
||||
## Tools
|
||||
|
||||
### pypi.org/p/potodo
|
||||
|
||||
``potodo`` helps us listing what still needs to be done in this mess
|
||||
of 500 files. It also synchroniszes with github issues to tell if
|
||||
someone is already working on a file, avoiding conflicts.
|
||||
|
||||
|
||||
## Tools
|
||||
|
||||
### pypi.org/p/pomerge
|
||||
|
||||
``pomerge`` helps us propagating translations from a branch to another,
|
||||
from a repo to another, or simply from a file to another.
|
||||
|
||||
|
||||
## Tools
|
||||
|
||||
### poautofill
|
||||
|
||||
``poautofill`` uses automatic translation to translate a whole file.
|
||||
This is bad from so many aspects, but it just helps me to avoid
|
||||
spending time trying to remember some vocabulary when I'm offline.
|
||||
|
||||
|
||||
# Et après ?
|
||||
|
||||
Venez nous aider :
|
||||
|
||||
- Sur github.com/python/python-docs-fr
|
||||
- Aux ateliers mensuels (meetup AFPy Paris)
|
||||
- Au sprint (2 jours) à La PyCon Fr à Bordeaux à partir du 31 oct 2019.
|
|
@ -0,0 +1,141 @@
|
|||
from matplotlib import pyplot as plt
|
||||
import datetime
|
||||
|
||||
"""Using something like:
|
||||
for i in $(seq -w 01 12)
|
||||
do
|
||||
git clean -dfqx >/dev/null
|
||||
git checkout -- . >/dev/null
|
||||
git checkout $(git log 3.9 --after "2020-$i-01" | grep ^commit | tail -n 1 | cut -d' ' -f2)
|
||||
git show | head -n 3
|
||||
python -c 'import sys; print("{:.1%}".format(int(sys.argv[1]) / int(sys.argv[2])))' \
|
||||
$(ls -1 *.po */*.po | grep -v 'whatsnew/changelog\|whatsnew/2\|whatsnew/3.[0-8]' | xargs msgcat | msgattrib --translated | grep -c '^msgid') \
|
||||
$(ls -1 *.po */*.po | grep -v 'whatsnew/changelog\|whatsnew/2\|whatsnew/3.[0-8]' | xargs msgcat | grep -c '^msgid')
|
||||
done
|
||||
"""
|
||||
|
||||
|
||||
plt.xkcd()
|
||||
|
||||
# According to `make progress`
|
||||
|
||||
progress = {
|
||||
datetime.date(2012, 10, 1): 0,
|
||||
datetime.date(2012, 12, 1): 4,
|
||||
datetime.date(2013, 12, 1): 4,
|
||||
datetime.date(2014, 11, 1): 4,
|
||||
datetime.date(2015, 12, 1): 5,
|
||||
datetime.date(2016, 1, 4): 6, # f8933be
|
||||
datetime.date(2016, 2, 1): 15, # very short untranslatable strings
|
||||
datetime.date(2016, 3, 4): 16, # 18c7d86
|
||||
datetime.date(2016, 4, 12): 17, # 4616b26
|
||||
datetime.date(2016, 5, 1): 18, # dd31bac
|
||||
datetime.date(2016, 6, 13): 20, # d16d992
|
||||
datetime.date(2016, 7, 3): 20, # 9e52ea9
|
||||
datetime.date(2016, 10, 17): 20, # efc39ad...
|
||||
# Changement de repo
|
||||
datetime.date(2016, 11, 5): 19, # e61fde28
|
||||
datetime.date(2017, 1, 17): 19, # 384a9e5c
|
||||
datetime.date(2017, 3, 5): 19.3, # 384a9e5c
|
||||
datetime.date(2017, 4, 2): 19.5,
|
||||
datetime.date(2017, 5, 10): 20,
|
||||
datetime.date(2017, 6, 1): 21.3,
|
||||
datetime.date(2017, 7, 6): 22.2,
|
||||
datetime.date(2017, 8, 1): 22.2,
|
||||
datetime.date(2017, 9, 5): 23.3,
|
||||
datetime.date(2017, 10, 2): 24.5,
|
||||
datetime.date(2017, 11, 5): 26.5,
|
||||
datetime.date(2017, 12, 1): 27.1,
|
||||
datetime.date(2018, 1, 4): 27.3,
|
||||
datetime.date(2018, 1, 30): 27.8,
|
||||
datetime.date(2018, 3, 1): 27.8,
|
||||
datetime.date(2018, 5, 21): 29.9,
|
||||
datetime.date(2018, 7, 2): 30,
|
||||
datetime.date(2018, 8, 1): 33,
|
||||
datetime.date(2018, 9, 15): 33.2,
|
||||
datetime.date(2018, 11, 1): 37.6,
|
||||
datetime.date(2018, 12, 7): 39.6,
|
||||
datetime.date(2019, 1, 2): 40.1,
|
||||
datetime.date(2019, 2, 3): 41,
|
||||
datetime.date(2019, 3, 1): 43.2,
|
||||
datetime.date(2019, 4, 2): 44.6,
|
||||
datetime.date(2019, 5, 6): 45,
|
||||
datetime.date(2019, 6, 3): 45.6,
|
||||
datetime.date(2019, 7, 2): 47.1,
|
||||
datetime.date(2019, 8, 13): 47.4,
|
||||
datetime.date(2019, 9, 3): 49.4,
|
||||
datetime.date(2019, 9, 30): 47.9, # Coût du passage en 3.8
|
||||
datetime.date(2019, 10, 2): 47.9,
|
||||
datetime.date(2019, 11, 1): 48.5,
|
||||
datetime.date(2019, 12, 1): 48.8,
|
||||
datetime.date(2020, 1, 2): 49.6,
|
||||
datetime.date(2020, 2, 1): 50.0,
|
||||
datetime.date(2020, 3, 3): 50.9,
|
||||
datetime.date(2020, 4, 1): 51.1,
|
||||
datetime.date(2020, 5, 1): 51.4,
|
||||
datetime.date(2020, 6, 5): 53.2,
|
||||
datetime.date(2020, 7, 1): 53.4,
|
||||
datetime.date(2020, 8, 4): 52.8,
|
||||
datetime.date(2020, 9, 9): 53.4,
|
||||
datetime.date(2020, 10, 1): 54.1,
|
||||
datetime.date(2020, 11, 6): 54.1,
|
||||
datetime.date(2020, 12, 2): 54.1,
|
||||
datetime.date(2021, 2, 2): 54.0,
|
||||
datetime.date(2021, 3, 1): 54.4,
|
||||
datetime.date(2021, 4, 1): 54.8,
|
||||
datetime.date(2021, 5, 4): 55.1,
|
||||
datetime.date(2021, 6, 4): 56.2,
|
||||
datetime.date(2021, 7, 14): 56.4,
|
||||
datetime.date(2021, 8, 5): 56.4,
|
||||
datetime.date(2021, 9, 6): 56.4,
|
||||
datetime.date(2021, 11, 1): 58,
|
||||
datetime.date(2022, 1, 1): 58.2,
|
||||
datetime.date(2022, 4, 5): 58.1,
|
||||
}
|
||||
|
||||
plt.rcParams["figure.figsize"] = (20, 10)
|
||||
|
||||
f, ax = plt.subplots(1)
|
||||
ax.plot_date(list(progress.keys()), list(progress.values()), linestyle="-")
|
||||
ax.annotate(
|
||||
"Bump to 3.10",
|
||||
(datetime.date(2021, 9, 24), 56.4),
|
||||
xytext=(datetime.date(2021, 9, 24), 40),
|
||||
arrowprops={"arrowstyle": "->"},
|
||||
)
|
||||
ax.annotate(
|
||||
"Bump to 3.9",
|
||||
(datetime.date(2020, 8, 4), 52.8),
|
||||
xytext=(datetime.date(2020, 6, 5), 35),
|
||||
arrowprops={"arrowstyle": "->"},
|
||||
)
|
||||
ax.annotate(
|
||||
"Bump to 3.8",
|
||||
(datetime.date(2019, 9, 30), 47.9),
|
||||
xytext=(datetime.date(2019, 9, 4), 30),
|
||||
arrowprops={"arrowstyle": "->"},
|
||||
)
|
||||
ax.annotate(
|
||||
"Meetups AFPy mensuels",
|
||||
(datetime.date(2018, 9, 1), 29.4),
|
||||
xytext=(-10, -40),
|
||||
textcoords="offset points",
|
||||
arrowprops={"arrowstyle": "->"},
|
||||
)
|
||||
ax.annotate(
|
||||
"/python/python-docs-fr/",
|
||||
(datetime.date(2016, 11, 5), 23.5),
|
||||
xytext=(-100, 50),
|
||||
textcoords="offset points",
|
||||
arrowprops={"arrowstyle": "->"},
|
||||
)
|
||||
ax.annotate(
|
||||
"Working on very short strings",
|
||||
(datetime.date(2016, 1, 15), (6 + 16) / 2),
|
||||
xytext=(-10, -50),
|
||||
textcoords="offset points",
|
||||
arrowprops={"arrowstyle": "->"},
|
||||
)
|
||||
plt.ylabel("%")
|
||||
ax.set_ylim(ymin=0)
|
||||
plt.savefig("fr_translation_percent.png")
|
After Width: | Height: | Size: 136 KiB |
After Width: | Height: | Size: 111 KiB |
After Width: | Height: | Size: 75 KiB |
After Width: | Height: | Size: 119 KiB |
After Width: | Height: | Size: 3.6 KiB |
After Width: | Height: | Size: 384 KiB |
After Width: | Height: | Size: 152 KiB |
After Width: | Height: | Size: 286 KiB |
After Width: | Height: | Size: 25 KiB |