espoir/python-docs-fr
Fork 0
forked from AFPy/python-docs-fr
Code Pull requests Activity

Updated README - More info on the getting started section (#623)

Browse source
This commit is contained in:
Jules Lasne (jlasne) 2019-03-22 10:21:12 +01:00 • committed by Julien Palard
commit 289b0b1b44
1 changed files with 43 additions and 26 deletions
Download patch file Download diff file Expand all files Collapse all files

69
README.rst
View file

@ -54,10 +54,10 @@ Prerequisites:
if you don't already have one).
Let's start:
Getting Started:
You'll need to fork the `python-docs-fr
<https://github.com/python/python-docs-fr>`_ clicking its ``Fork``
<https://github.com/python/python-docs-fr>`_ source repository by clicking its ``Fork``
button. This creates a copy of the whole project on your github
account: a place where you have the rights to do modifications.
@ -65,49 +65,59 @@ Step by step:
.. code-block:: bash
# Git clone your github fork using ssh (replace JulienPalard):
git clone git@github.com:JulienPalard/python-docs-fr.git
# Clone your github fork with `git` using ssh or https:
git clone git@github.com:YOUR_GITHUB_USERNAME/python-docs-fr.git
git clone https://github.com:YOUR_GITHUB_USERNAME/python-docs-fr.git
# Go to the cloned directory:
# Go into the cloned directory:
cd python-docs-fr/
# Add the upstream (the public repository) using HTTPS (won't ask for password):
# This is so git knows what/where the upstream is.
git remote add upstream https://github.com/python/python-docs-fr.git
All the translations must be made on the latest release.
We never translate on an oldest version, by example, the latest python release
is python 3.7, we don't want to translate directly on the python 3.5 release.
If needed translations would be backported on the oldest versions by the
`documentation team <https://www.python.org/dev/peps/pep-8015/#documentation-team>`.
Next, you need to find a file to work on.
You can use `potodo <https://github.com/seluj78/potodo>`, a tool made to find ``po`` to do.
Install it using pip (``pip install potodo``) in a ``python3.7`` environement.
Then run the command ``potodo`` in your cloned fork.
From the list returned by the command, you can choose any file that is not reserved.
First, you need to find a file to work on. You can use `potodo <https://github.com/seluj78/potodo>`.
Install it (``pip install potodo`` in a venv) and then run the command
`potodo` in your cloned fork.
From the list it spits out, you can choose any file that is not
reserved. We recommend not starting with a file from ``c-api`` as it is very technical.
**We recommend not starting with a file from ``c-api`` as it is very technical.**
Once you've choosen a file, please open an issue telling you're
working on it, to block someone from working on it.
Once you've choosen a file to work one, please open an `issue on github <https://github.com/python/python-docs-fr>` in the format of `I'm working on FOLDER/FILE.po`. This is done to update ``potodo`` as it checks the github API for reserved ``.po`` files in issues and pull requests.
Now you're ready to start a work session, each time you'll start a new task, start here:
Now you're ready to start a work session. Each time you'll start a new file, start here:
.. code-block:: bash
# To work, we'll need a branch, based on an up-to-date (freshly fetched)
# upstream/3.7 branch, let's say we'll work on glossary so we name
# the branch "glossary":
# upstream/3.7 branch. We will name our branch "library-sys" but you shall name yours
# whatever you want. Usually you'll name a branch based on the file you're working on.
# For example, If you're working on "library/venv.po" you can name your branch "library-venv"
# Update your local version to the latest
git fetch upstream
git checkout -b glossary upstream/3.7
# Create a new branch named "library-sys" based on "upstream/3.7"
git checkout -b library-sys upstream/3.7
# You can now work on the file, typically using poedit,
poedit directory/file.po
# Of course, replace "library/sys.po" by the file you've chose earlier
poedit library/sys.po
# When everything is clear (syntax errors from Sphinx, html rendering,
# semantics, typography),
# When you are done translating, you can run pospell (pip install pospell).
# This tool was made to check if you don't have any french mistakes.
# You can run the following command: pospell -p dict -l fr_FR **/*.po to check all files
# or replace **/*.po by your specific file (recommended).
# You can then run powrap (pip install powrap) which will rewrap
# You modified file to the correct line length of `80`.
# Run this command: `powrap **/*.po` or replace `**/*.po` with your modified file.
# When everything powrap and pospell passes without errors,
# you can commit your work with a nice explicit message:
git commit -a -m "Working on glossary."
git commit -a -m "Working on library/sys.po."
# Then push your modifications to your github clone,
# Then push your modifications to your github fork,
# as they are ephemeral branches, let's not configure git to track them all,
# "origin HEAD" is a "special" syntax to say "Push on origin,
# on a branch with the same name as the local one",
@ -145,6 +155,13 @@ Before commiting, you should use `grammalecte
<https://grammalecte.net/>`_ to check for your translations.
All the translations must be made on the latest release.
We never translate on an oldest version. For example, if the latest python release
is Python 3.7, we don't want to translate directly on the python 3.5 release.
If needed translations would be backported on the oldest versions by the
`documentation team <https://www.python.org/dev/peps/pep-8015/#documentation-team>`.
What to translate
~~~~~~~~~~~~~~~~~