forked from AFPy/python-docs-fr
Updated README - More info on the getting started section (#623)
This commit is contained in:
parent
7a36c822ca
commit
289b0b1b44
69
README.rst
69
README.rst
|
@ -54,10 +54,10 @@ Prerequisites:
|
||||||
if you don't already have one).
|
if you don't already have one).
|
||||||
|
|
||||||
|
|
||||||
Let's start:
|
Getting Started:
|
||||||
|
|
||||||
You'll need to fork the `python-docs-fr
|
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
|
button. This creates a copy of the whole project on your github
|
||||||
account: a place where you have the rights to do modifications.
|
account: a place where you have the rights to do modifications.
|
||||||
|
|
||||||
|
@ -65,49 +65,59 @@ Step by step:
|
||||||
|
|
||||||
.. code-block:: bash
|
.. code-block:: bash
|
||||||
|
|
||||||
# Git clone your github fork using ssh (replace JulienPalard):
|
# Clone your github fork with `git` using ssh or https:
|
||||||
git clone git@github.com:JulienPalard/python-docs-fr.git
|
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/
|
cd python-docs-fr/
|
||||||
|
|
||||||
# Add the upstream (the public repository) using HTTPS (won't ask for password):
|
# 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
|
git remote add upstream https://github.com/python/python-docs-fr.git
|
||||||
|
|
||||||
All the translations must be made on the latest release.
|
Next, you need to find a file to work on.
|
||||||
We never translate on an oldest version, by example, the latest python release
|
You can use `potodo <https://github.com/seluj78/potodo>`, a tool made to find ``po`` to do.
|
||||||
is python 3.7, we don't want to translate directly on the python 3.5 release.
|
Install it using pip (``pip install potodo``) in a ``python3.7`` environement.
|
||||||
If needed translations would be backported on the oldest versions by the
|
Then run the command ``potodo`` in your cloned fork.
|
||||||
`documentation team <https://www.python.org/dev/peps/pep-8015/#documentation-team>`.
|
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>`.
|
**We recommend not starting with a file from ``c-api`` as it is very technical.**
|
||||||
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.
|
|
||||||
|
|
||||||
Once you've choosen a file, please open an issue telling you're
|
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.
|
||||||
working on it, to block someone from working on it.
|
|
||||||
|
|
||||||
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
|
.. code-block:: bash
|
||||||
|
|
||||||
# To work, we'll need a branch, based on an up-to-date (freshly fetched)
|
# 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
|
# upstream/3.7 branch. We will name our branch "library-sys" but you shall name yours
|
||||||
# the branch "glossary":
|
# 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 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,
|
# 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,
|
# When you are done translating, you can run pospell (pip install pospell).
|
||||||
# semantics, typography),
|
# 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:
|
# 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,
|
# 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,
|
# "origin HEAD" is a "special" syntax to say "Push on origin,
|
||||||
# on a branch with the same name as the local one",
|
# 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.
|
<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
|
What to translate
|
||||||
~~~~~~~~~~~~~~~~~
|
~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
|
Loading…
Reference in New Issue
Block a user