Merge pull request #9 from carpentries-i18n/readme

.readthedocs.yml

@@ -0,0 +1,21 @@
+# .readthedocs.yml
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Build documentation in the docs/ directory with Sphinx
+sphinx:
+  configuration: conf.py
+
+# Optionally build your docs in additional formats such as PDF
+formats:
+  - pdf
+  - epub
+
+# Optionally set the version of Python and requirements required to build your docs
+python:
+  version: 3.7
+  install:
+    - requirements: requirements.txt

README.rst

@@ -0,0 +1,17 @@
+Carpentries Internationalisation Handbook
+=========================================
+
+.. image:: https://readthedocs.org/projects/carpentries-i18n-handbook/badge/?version=latest
+:target: https://carpentries-i18n-handbook.readthedocs.io/en/latest/?badge=latest
+:alt: Documentation Status
+
+This repository contains the Sphinx project with the information of how to
+translate and maintain the translations.
+
+The documentation is built `in Read the Docs`_.
+
+If you want to contribute to this repository, please follow our `Contributors guidelines`_.
+
+
+.. _in Read the Docs: https://carpentries-i18n-handbook.readthedocs.io/
+.. _Contributors guidelines: https://carpentries-i18n-handbook.readthedocs.io/en/latest/guide/contributor/

conf.py

@@ -41,7 +41,7 @@
 # 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', 'LICENSE.rst']
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store', 'LICENSE.rst', 'README.rst',]
 
 
 # -- Options for HTML output -------------------------------------------------

guide/contributor/00-download-and-build.rst

@@ -0,0 +1,86 @@
+Download and build
+==================
+
+
+You want to improve this guide? Let's start by building the documentation
+locally on your machine!
+
+We will use, `GitHub`_, `git`_, `Python`_, Python's `venv`_ module, and
+`Sphinx`_.
+
+
+.. note::
+
+   Some of the steps below assumes some level of familiarity with the tools. If
+   you don't know where to start exactly, do not panic! `Contact me`_ and we can
+   go through this together and find out what to add to make this guide even
+   better.
+
+
+
+Fork and clone the repository
+-----------------------------
+
+When contributing to a project hosted on GitHub is a good practice to `fork`_
+the project first under your username and `clone`_ your fork locally.
+
+.. code-block:: bash
+
+   git clone https://github.com/<YOUR-USER-NAME>/i18n-handbook.git
+   cd i18n-handbook
+
+
+It's also a good practice to keep an eye what happens ``upstream`` (source
+repository) by `configuring a remote`_ on your clone.
+
+.. code-block:: bash
+
+   git remote add upstream https://github.com/carpentries-i18n/i18n-handbook.git
+
+
+
+Creating an environment
+-----------------------
+
+To build the documentation locally it's recommended that you create an
+environment with the dependencies. For example on Linux or OSX you can do as:
+
+.. code-block:: bash
+
+   python -m venv ~/.venv/i18n-sphinx
+   source ~/.venv/i18n-sphinx/bin/activate
+   pip install -r requirements.txt
+
+refer to the `venv`_ tutorial to see how this is done on Windows.
+
+
+Build the documentation
+-----------------------
+
+Once you've got your environment setup you can go ahead and build the
+documentation locally with:
+
+.. code-block:: bash
+
+   sphinx-build -b html . _build
+
+
+To see what you've built then use:
+
+.. code-block:: bash
+
+   python -m http.server --directory _build/html
+
+
+That will serve the page on your machine under `<http://localhost:8000>`_ and you
+can see from your browser.
+
+.. _GitHub: https://help.github.com/en/github
+.. _git: https://swcarpentry.github.io/git-novice/
+.. _Python: https://www.python.org/
+.. _venv: https://docs.python.org/3/tutorial/venv.html
+.. _Sphinx: https://www.sphinx-doc.org/
+.. _fork: https://help.github.com/en/github/getting-started-with-github/fork-a-repo
+.. _clone: https://help.github.com/en/github/creating-cloning-and-archiving-repositories/cloning-a-repository-from-github
+.. _configuring a remote: https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/configuring-a-remote-for-a-fork
+.. _Contact me: https://github.com/dpshelio

guide/contributor/index.rst

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

index.rst

@@ -3,8 +3,8 @@
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
-Welcome to Translator's handbook's documentation!
-=================================================
+Welcome to Carpentries Internationalisation Handbook
+====================================================
 
 This guide documents the infrastructure to translate `the
 Carpentries`_'s lessons. In here we include a translator guide using `Transifex`_
@@ -25,6 +25,11 @@ And remember! also here you should follow our `Code of Conduct`_.
 
    guide/maintainer/index.rst
 
+.. toctree::
+   :maxdepth: 2
+   :caption: Contribute to this handbook
+
+   guide/contributor/index.rst
 
 TODO list
 ---------