Docs enhancements for v5.0.0 (#25)

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,7 @@
+**Description**:
+- ...
+
+**Checklist**:
+- [ ] My PR is ready for code review
+- [ ] I have added some tests, if applicable, and run the whole test suite, including linting tests
+- [ ] I have updated the documentation, if applicable

CONTRIBUTING.rst

@@ -0,0 +1,33 @@
+How to Contribute
+=================
+
+Contributions are welcome! Not familiar with the codebase yet? No problem!
+There are many ways to contribute to open source projects: reporting bugs,
+helping with the documentation, spreading the word and of course, adding
+new features and patches.
+
+Getting Started
+---------------
+* Make sure you have a GitHub account.
+* Open a `new issue <https://github.com/atlassistant/pytlas/issues>`_, assuming one does not already exist.
+* Clearly describe the issue including steps to reproduce when it is a bug.
+
+Making Changes
+--------------
+* Fork this repository.
+* Create a feature branch from where you want to base your work.
+* Make commits of logical units (if needed rebase your feature branch before
+  submitting it).
+* Check that your changes are `PEP8 <https://www.python.org/dev/peps/pep-0008/>`_ compliant (command `pylint pytlas setup.py` is your friend!).
+* Make sure your commit messages are well formatted.
+* If your commit fixes an open issue, reference it in the commit message (f.e. ``#15``).
+* Update the documentation as needed.
+* `Run all the tests <https://github.com/atlassistant/pytlas#testing>`_ to assure nothing else was accidentally broken.
+
+These guidelines also apply when helping with documentation.
+
+Submitting Changes
+------------------
+* Push your changes to a feature branch in your fork of the repository.
+* Submit a ``Pull Request``.
+* Wait for maintainer feedback.

README.rst

@@ -17,40 +17,47 @@ pytlas |travis| |cover| |pypi| |rtd| |license|
 .. |license| image:: https://img.shields.io/badge/License-GPL%20v3-blue.svg
     :target: https://www.gnu.org/licenses/gpl-3.0
 
-An open-source 🤖💬 python 3 assistant library built for people and made to be super easy to setup and understand.
+An open-source 🤖💬 Python 3 assistant library built for people and made to be super easy to setup and understand.
 
-**pytlas** translates natural language sentence into python skills you can easily define yourself.
+**pytlas** translates natural language sentence into python skills you can easily define yourself. It makes it really easy to develop your own Google Assistant, Alexa or whatever but runs on **your device** with **your trusted code** and **no connection** to obscure servers.
 
-I first started to develop `atlas <https://github.com/atlassistant/atlas>`_ but I have finally decided to develop a library that everyone could embed in their own program with simple python code.
+🌊 Want to get your feet wet? Have a look at the `example/skills` folder to see how it works!
 
-Want to get your feet wet? Have a look at the `example/skills` folder to see how it works!
+📚 Want to go futher and develop your own skill? Let's visit the `latest documentation <https://pytlas.readthedocs.io>`_ and share your work!
 
-Documentation
--------------
-
-The documentation is hosted on readthedocs here `https://pytlas.readthedocs.io <https://pytlas.readthedocs.io>`_.
+Quick start
+-----------
 
 Installation
-------------
+~~~~~~~~~~~~
 
 .. code-block:: bash
 
-  $ pip install -e .[snips] # Install pytlas and the snips interpreter backend
+  $ pip install pytlas[snips] # Gets the latest release from pypi
+  $ git clone https://github.com/atlassistant/pytlas && cd pytlas && pip install -e .[snips] # or directly from source
 
 Testing
--------
+~~~~~~~
 
-*When `pytest` is also installed, it may cause some tests to failed, so make sure it is not installed with `pip uninstall -y pytest` or use venv*
+*When `pytest` is also installed, it may cause some tests to fail, so make sure it is not installed with `pip uninstall -y pytest` or use venv*
 
 .. code-block:: bash
 
+  $ git clone https://github.com/atlassistant/pytlas && cd pytlas
   $ pip install -e .[snips,test]
   $ python -m nose --with-doctest --with-coverage --cover-package=pytlas
 
+Linting
+~~~~~~~
+
+.. code-block:: bash
+
+  $ pylint pytlas setup.py # in the root directory
+
 Contributing
 ------------
 
-Contributions are **welcome**! **pytlas** is being developed on my spare time so every help is greatly appreciated to push this project further.
+Contributions are **welcome**! **pytlas** is being developed my spare time so every help is greatly appreciated to push this project further.
 
 I have ideas!
 ~~~~~~~~~~~~~
@@ -60,7 +67,7 @@ Don't hesitate to submit them in the repo and we'll see what can be done.
 I have skills & time!
 ~~~~~~~~~~~~~~~~~~~~~
 
-Great, have a look at `NEXT.md <NEXT.md>`_ to see the big plans for upcoming releases or fix unresolved issues to start.
+Great, have a look at `the github project page <https://github.com/atlassistant/pytlas/projects/1>`_ to see the big plans for upcoming releases or fix unresolved issues to start.
 
 I have money!
 ~~~~~~~~~~~~~

docs/conf.py

@@ -16,7 +16,7 @@
 import os
 
 with open('../pytlas/version.py') as f:
-  __version__ = f.readline().strip()[15:-1]
+  __version__ = f.readlines()[1].strip()[15:-1]
 
 # -- Project information -----------------------------------------------------
 

docs/core_components/conversing.rst

@@ -1,16 +1,21 @@
 Conversing
 ==========
 
-The conversing domain use the :ref:`understanding` and :ref:`handling` domains to trigger python actions from parsed intents and maintain a conversation state.
+The conversing domain use the :ref:`understanding` and :ref:`handling` domains
+to trigger python actions from parsed intents and maintain a conversation
+state.
 
 .. _agents:
 
 Agent
 -----
 
-An agent represent the interface between the user and loaded skills. It maintain the conversation state and use an underlying interpreter to understand the user.
+An agent represent the interface between the user and loaded skills. It
+maintain the conversation state and use an underlying interpreter to understand
+the user.
 
-The agent is the entry point which will take raw user inputs with its `parse` method and call loaded handlers as needed.
+The agent is the entry point which will take raw user inputs with its `parse`
+method and call loaded handlers as needed.
 
 Entry point
 ~~~~~~~~~~~
@@ -21,7 +26,10 @@ Entry point
 
   More information on :ref:`meta`.
 
-When an intent has been found, it will try to find an handler for this specific intent and call it. It will then manage the conversation, handle cancel and fallback intents and communicate back to the user using its internal :ref:`client`.
+When an intent has been found, it will try to find an handler for this specific
+intent and call it. It will then manage the conversation, handle cancel and
+fallback intents and communicate back to the user using its internal
+:ref:`client`.
 
 From a skill
 ~~~~~~~~~~~~
@@ -38,9 +46,12 @@ From a skill perspective, here are the method you will use.
 Client
 ------
 
-A client is a thin layer used by an agent to communicate with the user. It can be anything such as a tiny CLI (as the one provided), a WebSocket server or a connected speaker.
+A client is a thin layer used by an agent to communicate with the user. It can
+be anything such as a tiny CLI (as the one provided), a WebSocket server or a
+connected speaker.
 
-When provided to an agent (using its `model` property), some specific members will be called by the agent on specific lifecycle events:
+When provided to an agent (using its `model` property), some specific members
+will be called by the agent on specific lifecycle events:
 
 .. py:function:: on_answer(text, cards, raw_text, **meta)
 
@@ -60,4 +71,4 @@ When provided to an agent (using its `model` property), some specific members wi
 
 .. py:function:: on_context(context_name)
 
-  Called when the agent context has changed.
+  Called when the agent context has changed.

docs/core_components/handling.rst

@@ -3,16 +3,20 @@
 Handling
 ========
 
-The handling domain enables skills to register their data such as **meta**, **handlers** and **translations**.
+The handling domain enables skills to register their data such as **meta**,
+**handlers** and **translations**.
 
-This is where you, as a developer, will spend most your time, see :ref:`skills` for more info.
+This is where you, as a developer, will spend most of your time, see
+:ref:`skills` for more info.
 
-Basically, it's just a python module which uses `pytlas` decorators to register some specific components on the running environment.
+Basically, you will just declare a python module and use `pytlas` decorators
+to register some specific components on the running environment.
 
 Handlers store
 --------------
 
-Handlers are register on an instance of an `HandlersStore`, mostly using the `intent` decorator.
+Handlers are register on an instance of an `HandlersStore`, mostly using the
+`intent` decorator.
 
 .. autoclass:: pytlas.handling.HandlersStore
   :members:
@@ -28,7 +32,8 @@ Skill meta are registered on a `MetasStore`, mostly using the `meta` decorator.
 Translations store
 ------------------
 
-Translations are registered on a `TranslationsStore` instance, mostly using the `translations` decorator.
+Translations are registered on a `TranslationsStore` instance, mostly using the
+`translations` decorator.
 
 .. autoclass:: pytlas.handling.TranslationsStore
-  :members:
+  :members:

docs/core_components/index.rst

@@ -1,7 +1,9 @@
 Core components
 ===============
 
-In order to develop for pytlas, you should understand how core components fit together to make it understand and call your handlers. If you only want to develop your own skills, you can omit this section and go to :ref:`skills`.
+In order to develop for pytlas, you should understand how core components fit
+together to make it understand and call your handlers. If you only want to
+develop your own skills, you can omit this section and go to :ref:`skills`.
 
 The general command flow looks like this:
 
@@ -18,4 +20,4 @@ The general command flow looks like this:
   handling
   conversing
   settings
-  meta
+  meta

docs/core_components/meta.rst

@@ -10,7 +10,9 @@ Especially in:
 - The agent `__init__`, `answer`, `ask` and `parse` methods,
 - The `Intent` class
 
-Those metadata represents any non consumed keyword parameters. They are pretty useful when you need to provide additional information but should never be considered mandatory.
+Those metadata represents any non consumed keyword parameters. They are pretty
+useful when you need to provide additional information but should never be
+considered mandatory.
 
 Here is a code example for a skill:
 
@@ -35,7 +37,8 @@ Here is a code example for a skill:
     
     return r.agent.done()
 
-With this definition, if I call the `parse` method with some meta, it will handle my position, else, it will fallback to search the weather for a city:
+With this definition, if I call the `parse` method with some meta, it will
+handle my position, else, it will fallback to search the weather for a city:
 
 .. code-block:: python
   
@@ -47,4 +50,4 @@ With this definition, if I call the `parse` method with some meta, it will handl
   agent.parse("What's the weather like", latitude=49, longitude=1)
 
   # Will fallback to the city one
-  agent.parse("What's the weather like in Paris")
+  agent.parse("What's the weather like in Paris")

docs/core_components/settings.rst

@@ -1,12 +1,14 @@
 Settings
 ========
 
-Settings enables all parts of pytlas to read config data and is already covered in :ref:`settings`.
+Settings enables all parts of pytlas to read config data and is already
+covered in :ref:`settings`.
 
 Settings store
 --------------
 
-The settings store holds config data. The global store is available as `pytlas.settings.CONFIG` property.
+The settings store holds config data. The global store is available as
+`pytlas.settings.CONFIG` property.
 
 .. autoclass:: pytlas.settings.SettingsStore
-  :members:
+  :members:

docs/core_components/understanding.rst

@@ -3,33 +3,41 @@
 Understanding
 =============
 
-The understanding domain groups all thing related to the understanding of user intents.
+The understanding domain groups all thing related to the understanding of user
+intents.
 
 .. _interpreter:
 
 Interpreter
 -----------
 
-Interpreter allow pytlas to categorize user intents and to extract slots from raw text. Whatever interpreter you decide to use, it will need training data to be able to understand what's the user intent behind an input sentence.
+Interpreter allow pytlas to categorize user intents and to extract slots from
+raw text. Whatever interpreter you decide to use, it will need training data to
+be able to understand what's the user intent behind an input sentence.
 
 Intent
 ~~~~~~
 
 An intent represents a user intention.
 
-For example, when I say *what's the weather like?*, my intent is something as *get weather*. When I say *please tell me what's the weather like today*, it maps to the same intent *get weather*.
+For example, when I say *what's the weather like?*, my intent is something as
+*get weather*. When I say *please tell me what's the weather like today*, it
+maps to the same intent *get weather*.
 
 Slot
 ~~~~
 
-A slot is like a parameter value for a function. It represents an entity in the context of an intent.
+A slot is like a parameter value for a function. It represents an entity in the
+context of an intent.
 
-So when I say *what's the weather like in Paris?*, my intent is *get weather* and the slot *city* should be *Paris*.
+So when I say *what's the weather like in Paris?*, my intent is *get weather*
+and the slot *city* should be *Paris*.
 
 Implementing a custom interpreter
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-If you wish to implement your own interpreter, you must at least extends from `pytlas.interpreters.Interpreter` and implement those methods.
+If you wish to implement your own interpreter, you must at least extends from
+`pytlas.interpreters.Interpreter` and implement those methods.
 
 .. note::
 
@@ -42,7 +50,8 @@ If you wish to implement your own interpreter, you must at least extends from `p
 Trainings store
 ---------------
 
-All training data are registered on a `TrainingsStore` instance, mostly using the `training` decorator.
+All training data are registered on a `TrainingsStore` instance, mostly using
+the `training` decorator.
 
 .. autoclass:: pytlas.understanding.TrainingsStore
-  :members:
+  :members:

docs/getting_started/index.rst

@@ -6,6 +6,6 @@ Here is the basic steps to get you started quickly with **pytlas**.
 .. toctree::
   :maxdepth: 2
   :caption: Contents
-  
+
   installation
-  usage
+  usage

docs/getting_started/installation.rst

@@ -3,7 +3,8 @@
 Installation
 ============
 
-There's multiple way to install pytlas. You're free to pick the one that better fit your needs.
+There's multiple way to install pytlas. You're free to pick the one that better
+fit your needs.
 
 .. note::
 
@@ -38,7 +39,8 @@ From source
 Choosing your interpreter
 -------------------------
 
-In order to understand natural language, pytlas is backed by :ref:`interpreter` which may need additional installation steps.
+In order to understand natural language, pytlas is backed by :ref:`interpreter`
+which may need additional installation steps.
 
 .. _installation_snips:
 
@@ -47,4 +49,7 @@ snips
 
 The official interpreter use the fantastic `snips-nlu <https://github.com/snipsco/snips-nlu>`_ python library.
 
-Given the language you want your assistant to understand, it will need to download additional resources. Fortunately, you don't have to do it manually since `v5.0.0`, pytlas will automatically try to download them when fitting the interpreter with a language it doesn't know already.
+Given the language you want your assistant to understand, it will need to
+download additional resources. Fortunately, you don't have to do it manually
+since `v5.0.0`, pytlas will automatically try to download them when fitting the
+interpreter with a language it doesn't know already.