Merge pull request #7 from carpentries-i18n/firststeps

LICENSE.rst

@@ -0,0 +1,85 @@
+License
+=======
+
+Documentation
+-------------
+
+The Carpentries documentation material in this repository is
+made available under the [Creative Commons Attribution
+license][cc-by-human]. The following is a human-readable summary of
+(and not a substitute for) the `full legal text of the CC BY 4.0
+license`_.
+
+You are free:
+
+* to **Share**---copy and redistribute the material in any medium or format
+* to **Adapt**---remix, transform, and build upon the material
+
+for any purpose, even commercially.
+
+The licensor cannot revoke these freedoms as long as you follow the
+license terms.
+
+Under the following terms:
+
+* **Attribution**---You must give appropriate credit (mentioning that
+  your work is derived from work that is Copyright © The Carpentries
+  and, where practical, linking to
+  http://carpentries.org/), provide a `link to the
+  license`_, and indicate if changes were made. You may do
+  so in any reasonable manner, but not in any way that suggests the
+  licensor endorses you or your use.
+
+**No additional restrictions**---You may not apply legal terms or
+technological measures that legally restrict others from doing
+anything the license permits.  With the understanding that:
+
+Notices:
+
+* You do not have to comply with the license for elements of the
+  material in the public domain or where your use is permitted by an
+  applicable exception or limitation.
+* No warranties are given. The license may not give you all of the
+  permissions necessary for your intended use. For example, other
+  rights such as publicity, privacy, or moral rights may limit how you
+  use the material.
+
+Software
+--------
+
+Except where otherwise noted, the example programs and other software
+provided by The Carpentries are made available under the
+`OSI`_-approved `MIT license`_.
+
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+Trademark
+---------
+
+"The Carpentries", "Software Carpentry", "Data Carpentry", and "Library Carpentry" and their respective logos
+are registered trademarks of `Community Initiatives`_.
+
+
+.. _full legal text of the CC BY 4.0 license: https://creativecommons.org/licenses/by/4.0/legalcode
+.. _link to the license: https://creativecommons.org/licenses/by/4.0/
+.. _MIT license: https://opensource.org/licenses/mit-license.html
+.. _OSI: https://opensource.org/
+.. _Community Initiatives: http://communityin.org/

conf.py

@@ -12,14 +12,17 @@
 #
 import os
 import sys
+import datetime
 sys.path.insert(0, os.path.abspath('.'))
+today_date = datetime.date.today()
 
 
 # -- Project information -----------------------------------------------------
 
 project = "Translator's handbook"
-copyright = '2019, i18n team'
-author = 'i18n team'
+author = "The Carpentrie's i18n team"
+copyright = f"2019-{today_date:%Y}, {author}. Creative Commons Attribution 4.0 International license."
+
 
 
 # -- General configuration ---------------------------------------------------
@@ -28,6 +31,8 @@
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
+    "sphinx.ext.extlinks",
+    "sphinx.ext.todo",
 ]
 
 # Add any paths that contain templates here, relative to this directory.
@@ -36,17 +41,26 @@
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
 # This pattern also affects html_static_path and html_extra_path.
-exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store', 'LICENSE.rst']
 
 
 # -- Options for HTML output -------------------------------------------------
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-html_theme = 'alabaster'
+html_theme = "sphinx_rtd_theme"
 
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
 html_static_path = ['_static']
+
+extlinks = {'project': ('https://github.com/orgs/carpentries-i18n/projects/%s',
+                        'project '),
+            'org-repo': ('https://github.com/carpentries-i18n/%s', ''),
+            'commit-png': ('https://github.com/carpentries-i18n/python-novice-gapminder/commit/%s', 'commit '),
+            }
+
+todo_include_todos = True
+todo_link_only = True

copyright.rst

@@ -0,0 +1 @@
+LICENSE.rst

guide/maintainer/00_starting.rst

@@ -0,0 +1,13 @@
+Getting started
+===============
+
+To be the maintainer of this infrastructure doesn't require that you speak other
+thing than English! However, you should be fluent with few technologies: ``git``,
+``jekyll``, ``sphinx``, ``python`` and ``gettext``.
+
+Are you interested to help? Keep reading the guide and introduce yourself on the
+`internationalisation slack room`_ (`or matrix`_) and search for ``DavidPS``.
+
+
+.. _internationalisation slack room: https://swcarpentry.slack.com/archives/CL357S0CD
+.. _or matrix: https://matrix.to/#/!ClFjaMVdhUWeijQNJe:matrix.org?via=matrix.org&via=petrichor.me

guide/maintainer/01_understanding.rst

@@ -0,0 +1,45 @@
+Understanding the structure
+===========================
+
+At the moment there are translation support for two types of sources:
+
+- carpentries lessons using `jekyll`_ (:project:`1`)
+- carpentries documentation using `sphinx`_ (:project:`4`)
+
+The other type of material is the lessons based on |rmarkdown|_. There is the
+:project:`2` with issues to tackle the implementation of that type of lessons.
+
+The goal is that everything is translated using `gettext`_ system. This system
+converts the source product into a ``PO`` file format that many translation
+software understand and it is therefore easier to update when the source changes
+and find what bits are new. All the issues related with the tooling and
+infrastructure is at the :project:`3`.
+
+The Carpentries-i18n organisation
+---------------------------------
+
+`This organisation`_ includes, for now forks of all the lessons and other
+repositories with code needed to convert, automate and visualise the lessons and
+their translations.
+
+.. note::
+   At the moment the material and all the repositories in this organisation is
+   not officially under `The Carpentries`_ umbrella. However, the people behind
+   this effort are part of the Carpentries' community.
+
+The mains repositories are:
+
+- :org-repo:`i18n-handbook` - The source of this documentation.
+- :org-repo:`i18n` - The machinery to support the ``jekyll`` lessons.
+- :org-repo:`carp-theme` - A `Jekyll theme`_ to render the lessons with multilingual support
+- :org-repo:`handbook-translations` - Translations repository for the
+  `Carpentries handbook`_ that uses sphinx.
+.. _jekyll: https://jekyllrb.com/
+.. _sphinx: https://www.sphinx-doc.org/
+.. |rmarkdown| replace:: ``rmarkdown``
+.. _rmarkdown: https://rmarkdown.rstudio.com/
+.. _gettext: https://en.wikipedia.org/wiki/Gettext
+.. _This organisation: https://github.com/carpentries-i18n
+.. _The Carpentries: https://carpentries.org/
+.. _Jekyll theme: https://jekyllrb.com/docs/themes/
+.. _Carpentries handbook: https://docs.carpentries.org/

guide/maintainer/02_jekyll.rst

@@ -0,0 +1,125 @@
+Working with Jekyll lessons
+===========================
+
+Prepare the lesson
+------------------
+
+To prepare a jekyll-based lesson for translation we need few steps:
+
+#. Fork the repository under :org-repo:``
+#. Set-it up to use the Jekyll-theme (i.e., remove everything that's not lesson content).
+#. Create it as a submodule within the :org-repo:`i18n` repository.
+#. Generate the `po` files using :org-repo:`po4gitbook` software.
+#. Since `po4gitbook` generates the whole lesson as a single file, break it into espisodes with ``splitpot.py``.
+#. Create the project on Transifex and push the source files.
+
+The first three steps can be done automatically using ``lesson2theme.py`` from
+:org-repo:`i18n`. You'll need to `create an access token on GitHub`_
+
+.. code-block:: bash
+
+   $ cd i18n
+   i18n (git)-[master]$ export gh_access_token=xxxxxxxx
+   i18n (git)-[master]$ python helpers/lesson2theme.py swcarpentry/python-novice-gapminder
+   i18n (git)-[python-novice-gapminder]$
+
+
+That command:
+
+#. forks the repository,
+#. fixes any recognised formatting issues that will affect the conversion to PO
+   (e.g., :commit-png:`52cacd8`),
+#. removes everything that's provided by the theme (e.g., :commit-png:`682a376`),
+   and
+#. updates ``_config.yml`` so it accepts multiple languages (e.g.,
+   :commit-png:`f4e6e3b`).
+#. Then adds the forked repo as a submodule to :org-repo:`i18n` repository in a
+   branch with the lessons name.
+
+The output of the above command gives you the link of the forked repository so
+the result can be checked manually with a list of the following steps that are
+to be done manually.
+
+The first of these steps is to run ``po4gitbook`` to update/generate the ``po`` files.
+
+.. warning::
+
+   If the command gets stuck for more than a couple of seconds that's due to
+   some formatting issues as the once fixed on the second step above.
+
+.. note::
+
+   The ``update.sh`` goes through all the md files, finds whether there's been
+   an update on the sources and propagates to new files, if they've changed
+   tries to merge them and marks the blocks as fuzzy if the source has changed.
+
+Now you should have a new file under the ``po`` directory:
+
+.. code-block:: bash
+
+   i18n (git)-[python-novice-gapminder]$ po4gitbook/update.sh
+   ...
+   i18n (git)-[python-novice-gapminder]$ ls po
+   ...
+   python-novice-gapminder.pot
+   ...
+
+
+That ``pot`` file is the template that we will use to break it up into chunks
+first and then send these to transifex.
+
+.. code-block:: bash
+
+   i18n (git)-[python-novice-gapminder]$ python helpers/splitpot.py po/python-novice-gapminder.pot
+   ...
+   i18n (git)-[python-novice-gapminder]$ ls transifex/python-novice-gapminder/pot
+   00__CODE_OF_CONDUCT.md.pot  06__03-types-conversion.md.pot  12__09-plotting.md.pot           18__15-coffee.md.pot             24__about.md.pot      30__aio.md.pot
+   01__CONTRIBUTING.md.pot     07__04-built-in.md.pot          13__10-lunch.md.pot              19__16-writing-functions.md.pot  25__design.md.pot     31__index.md.pot
+   ...
+
+
+Then we need to create the target language directory we want (e.g., ``es`` for
+Spanish), and let Transifex's command line tool (``tx``) to prepare the files
+
+.. code-block:: bash
+
+   i18n (git)-[python-novice-gapminder]$ mkdir -p transifex/python-novice-gapminder/es
+   i18n (git)-[python-novice-gapminder]$ cd transifex/python-novice-gapminder
+   python-novice-gapminder (git)-[python-novice-gapminder]$ cd transifex/python-novice-gapminder
+   python-novice-gapminder (git)-[python-novice-gapminder]$ tx config mapping-bulk -p python-novice-gapminder --source-language en --type PO -f '.pot' \
+                   --source-file-dir pot --expression "<lang>/{filename}.po" --execute
+
+
+The last command generates a ``config`` file under a hidden ``.tx`` directory.
+We need then to `add the project in Transifex`_ where we need to input a name
+(same as the lesson), select that's a public project, add the url of the
+project, select that's a file-based project, assign it to the
+``carpentries-translation`` team and select the target languages (by default it
+adds all that we've used before).
+
+.. image:: images/Transifex_add_project.png
+   :width: 600
+   :alt: Sample of how to fill up Transifex form.
+
+
+Once the project is created in transifex we can push the project using ``tx``:
+
+.. code-block:: bash
+
+   python-novice-gapminder (git)-[python-novice-gapminder]$  tx push -s --parallel
+
+Once the upload has been completed, you should see the resources available in
+the project page in Transifex (e.g., `python-novice-gapminder
+<https://www.transifex.com/carpentries-i18n/python-novice-gapminder/dashboard/>`_)
+
+Bring the translations to the rendered page
+-------------------------------------------
+
+.. todo::
+
+   add details about how to bring the translated strings.
+
+
+
+.. _create an access token on GitHub: https://help.github.com/en/github/authenticating-to-github/creating-a-personal-access-token-for-the-command-line
+.. _add the project in Transifex: https://www.transifex.com/carpentries-i18n/add/

guide/maintainer/index.rst

@@ -0,0 +1,8 @@
+Maintainer Guide
+================
+
+.. toctree::
+   :maxdepth: 2
+   :glob:
+
+   *

guide/translator/00_starting.rst

@@ -0,0 +1,10 @@
+Getting started
+===============
+
+Do you speak any other language besides English? Would you like to use that
+skill to translate any of `the Carpentries`_' material? Then you are in
+the right place!
+
+
+
+.. _the Carpentries: https://carpentries.org/

guide/translator/index.rst

@@ -0,0 +1,8 @@
+Translator Guide
+================
+
+.. toctree::
+   :maxdepth: 2
+   :glob:
+
+   *