Documentation update

CONTRIBUTING.rst

@@ -38,8 +38,8 @@ and "help wanted" is open to whoever wants to implement it.
 Write Documentation
 ~~~~~~~~~~~~~~~~~~~
 
-glossary could always use more documentation, whether as part of the
-official glossary docs, in docstrings, or even on the web in blog posts,
+`glosario` could always use more documentation, whether as part of the
+official `glosario` docs, in docstrings, or even on the web in blog posts,
 articles, and such.
 
 Submit Feedback
@@ -57,18 +57,23 @@ If you are proposing a feature:
 Get Started!
 ------------
 
-Ready to contribute? Here's how to set up `glossary` for local development.
+Ready to contribute? Here's how to set up `glosario` for local development.
 
-1. Fork the `glossary` repo on GitHub.
+1. Fork the `glosario` repo on GitHub.
 2. Clone your fork locally::
 
-    $ git clone [email protected]:your_name_here/glossary.git
+    $ git clone [email protected]:your_name_here/glosario.git
 
-3. Install your local copy into a virtualenv. Assuming you have virtualenvwrapper installed, this is how you set up your fork for local development::
+3. `glosario` uses `poetry` for package management and setup.
 
-    $ mkvirtualenv glosario
-    $ cd glosario/
-    $ python setup.py develop
+Ensure that  `poetry` is installed::
+
+    $ curl -sSL https://raw.githubusercontent.com/python-poetry/poetry/master/get-poetry.py | python -
+
+Once installed, and within the cloned repository dir, create a virtual environment and install dependences::
+
+    $ poetry shell
+    $ poetry install 
 
 4. Create a branch for local development::
 
@@ -77,14 +82,12 @@ Ready to contribute? Here's how to set up `glossary` for local development.
    Now you can make your changes locally.
 
 5. When you're done making changes, check that your changes pass flake8 and the
-   tests, including testing other Python versions with tox::
+   tests::
 
     $ flake8 glosario tests
     $ python setup.py test or py.test
     $ tox
 
-   To get flake8 and tox, just pip install them into your virtualenv.
-
 6. Commit your changes and push your branch to GitHub::
 
     $ git add .
@@ -93,6 +96,14 @@ Ready to contribute? Here's how to set up `glossary` for local development.
 
 7. Submit a pull request through the GitHub website.
 
+Building this documentation
+----------------------------
+The project's documentation can be found in the ``docs/`` dir and is built with `sphinx <https://www.sphinx-doc.org/en/master/index.html>`_. Once you have a local environment setup as described above, you can build the documentation by either running `make.bat` on windows or typing on Linux/Mac::
+
+    $ make 
+
+This compiles the reStructuredText into html. 
+
 Pull Request Guidelines
 -----------------------
 
@@ -106,12 +117,6 @@ Before you submit a pull request, check that it meets these guidelines:
    https://travis-ci.org/ian-flores/glosario/pull_requests
    and make sure that the tests pass for all supported Python versions.
 
-Tips
-----
-
-To run a subset of tests::
-
-    $ py.test tests.test_glosario
 
 Deploying
 ---------

README.md

@@ -2,7 +2,7 @@
 
 [![Documentation Status](https://readthedocs.org/projects/glosario/badge/?version=latest)](https://glosario.readthedocs.io/en/latest/?badge=latest)
 
-Package to define technical terms
+This python package enables programatic access to the [glosario](https://github.com/carpentries/glosario) glossary of technical terms. These definitions are used in the context of Carpentries lessons, where newly introduced terms require clarification. 
 
 ### Installation:
 

docs/index.rst

@@ -1,7 +1,8 @@
 Welcome to glosario's documentation!
 ===========================================================
 
-Package to define technical terms
+This python package enables programatic access to the `glosario <https://github.com/carpentries/glosario>`_ glossary of technical terms. These definitions are used in the context of Carpentries lessons, where newly introduced terms require clarification. The glossary is stored in a `single large YAML file <https://github.com/carpentries/glosario/blob/master/glossary.yml>`_ that is updated by contributors and authors of lessons.
+
 
 To get started, check out the sections below:
 
@@ -11,6 +12,7 @@ To get started, check out the sections below:
 
    installation
    usage
+   yaml_synchronization
    contributing
    conduct
    contributors

docs/yaml_synchronization.rst

@@ -0,0 +1,8 @@
+=====
+Glosario YAML Synchronization
+=====
+
+This project uses the `glosario <https://github.com/carpentries/glosario>`_ `YAML file <https://github.com/carpentries/glosario/blob/master/glossary.yml>`_, which contains the glossary of technical terms. In order to keep an updated copy of that file within this project, a GitHub Action is used on a daily basis to schedule an import into the repository. The Action relies on the util script in ``utils/download_data.py``. Since the import is run once a day, you can expect that the file may be out of date for up to 24 hours when you first check out this project or this project is installed from pip.
+
+However, currently once this project is installed there is no method for synchronization and the glossary will remain out of date unless ``utils/download_data.py`` is manually run once again. 
+