Merge pull request #1152 from RasaHQ/valid-docs-during-build

Validate docs during travis build

.travis.yml

@@ -9,7 +9,6 @@ python:
 - '3.5'
 - '3.6'
 install:
-- sudo apt-get update
 - sudo apt-get install graphviz graphviz-dev
 - pip install -r dev-requirements.txt
 - pip install -e .
@@ -30,10 +29,17 @@ jobs:
     - swagger-cli validate docs/_static/spec/server.yml
     after_success:
     - coveralls
-  - stage: docs
+  - stage: Test Docs
+    install:
+    - pip install -r docs-requirements.txt
+    - pip install -e .
+    - pip list
+    script:
+      # be strict about warnings --> they will be treated as errors
+    - cd docs && make SPHINXOPTS="-W --keep-going -A html_theme=rasabaster" html
+  - stage: build docs
     if: fork = false AND branch = "master"
     install:
-    - sudo apt-get update
     - pip install -r docs-requirements.txt
     - pip install -e .
     - pip list

README.md

@@ -6,19 +6,19 @@
 [![Documentation Status](https://img.shields.io/badge/docs-stable-brightgreen.svg)](https://rasa.com/docs/core)
 
 
-- **What do Rasa Core & NLU do? 🤔** 
+- **What do Rasa Core & NLU do? 🤔**
   [Read About the Rasa Stack](https://rasa.com/products/rasa-stack/)
 
-- **I'd like to read the detailed docs 🤓** 
+- **I'd like to read the detailed docs 🤓**
   [Read The Docs](https://rasa.com/docs/core)
 
-- **I'm ready to install Rasa Core! 🚀** 
+- **I'm ready to install Rasa Core! 🚀**
   [Installation](https://rasa.com/docs/core/installation.html)
 
-- **I have a question ❓** 
+- **I have a question ❓**
   [Rasa Community Forum](https://forum.rasa.com)
 
-- **I would like to contribute 🤗** 
+- **I would like to contribute 🤗**
   [How to contribute](#how-to-contribute)
 
 
@@ -38,25 +38,25 @@ But you can also build assistants as
 - Alexa Skills
 - Google Home Actions
 
-Rasa Core's primary purpose is to help you build contextual, layered 
-conversations with lots of back-and-forth. To have a real conversation, 
+Rasa Core's primary purpose is to help you build contextual, layered
+conversations with lots of back-and-forth. To have a real conversation,
 you need to have some memory and build on things that were said earlier.
 Rasa Core lets you do that in a scalable way.
 
-There's a lot more background information in this 
+There's a lot more background information in this
 [blog post](https://medium.com/rasa-blog/a-new-approach-to-conversational-software-2e64a5d05f2a)
 
 ## Where to get help
 
 There is extensive documentation:
 
-- [master](https://rasa.com/docs/core/master/)  
-  (if you install from **github**) or 
-- [stable](https://rasa.com/docs/core)   
+- [master](https://rasa.com/docs/core/master/) 
+  (if you install from **github**) or
+- [stable](https://rasa.com/docs/core)  
   (if you install from **pypi**)
 
 
-Please use [Rasa Community Forum](https://forum.rasa.com) for quick answers to 
+Please use [Rasa Community Forum](https://forum.rasa.com) for quick answers to
 questions.
 
 
@@ -67,20 +67,20 @@ questions.
 - [License](#license)
 
 ### How to contribute
-We are very happy to receive and merge your contributions. There is 
-some more information about the style of the code and docs in the 
+We are very happy to receive and merge your contributions. There is
+some more information about the style of the code and docs in the
 [documentation](https://nlu.rasa.com/contribute.html).
 
 In general the process is rather simple:
-1. create an issue describing the feature you want to work on (or 
-   have a look at issues with the label 
+1. create an issue describing the feature you want to work on (or
+   have a look at issues with the label
    [help wanted](https://github.com/RasaHQ/rasa_core/issues?q=is%3Aissue+is%3Aopen+label%3A%22help+wanted%22))
 2. write your code, tests and documentation
 3. create a pull request describing your changes
 
-You pull request will be reviewed by a maintainer, who might get 
-back to you about any necessary changes or questions. You will 
-also be asked to sign a 
+You pull request will be reviewed by a maintainer, who might get
+back to you about any necessary changes or questions. You will
+also be asked to sign a
 [Contributor License Agreement](https://cla-assistant.io/RasaHQ/rasa_core)
 
 
@@ -104,7 +104,7 @@ You can now change the docs locally and the web page will automatically reload
 and apply your changes.
 
 ## License
-Licensed under the Apache License, Version 2.0. 
+Licensed under the Apache License, Version 2.0.
 Copyright 2018 Rasa Technologies GmbH. [Copy of the license](LICENSE.txt).
 
 A list of the Licenses of the dependencies of the project can be found at

docs-requirements.txt

@@ -1,4 +1,4 @@
-sphinx==1.7.5
+sphinx==1.8.1
 sphinx-autobuild==0.7.1
 sphinxcontrib-programoutput==0.11
 nbsphinx==0.3.2

docs/api/agent.rst

@@ -16,6 +16,3 @@ that lets you access most of Rasa Core's functionality.
 
 
 .. include:: ../feedback.inc
-
-.. raw:: html
-   :file: ../livechat.html	

docs/api/dispatcher.rst

@@ -0,0 +1,11 @@
+Dispatcher
+==========
+
+The dispatcher is your connection to the outside world and allows you to
+send messages back to the user.
+
+.. autoclass:: rasa_core.dispatcher.Dispatcher
+    :members:
+
+
+.. include:: ../feedback.inc

docs/api/events.rst

@@ -273,7 +273,3 @@ Log an executed action
 
 
 .. include:: ../feedback.inc
-
-.. raw:: html
-   :file: ../livechat.html
-

docs/api/featurizer.rst

@@ -46,7 +46,8 @@ of the tracker has a couple steps:
             The vectors ``X, y`` indicate a presence of a certain intent,
             entity, previous action or slot e.g. ``[0 0 1 0 0 1 ...]``.
 
-        - ``LabelTokenizerSingleStateFeaturizer`` creates an vector based on the feature label:
+        - ``LabelTokenizerSingleStateFeaturizer`` creates an vector
+            based on the feature label:
             All active feature labels (e.g. ``prev_action_listen``) are split
             into tokens and represented as a bag-of-words. For example, actions
             ``utter_explain_details_hotel`` and
@@ -84,25 +85,32 @@ different tracker featurizers:
 1. Full Dialogue
 ----------------
 
-``FullDialogueTrackerFeaturizer`` creates numerical representation of stories to feed to a recurrent neural network
-where the whole dialogue is fed to a network and the gradient is backpropagated from all time steps.
-Therefore, ``X`` is an array of shape ``(num_stories, max_dialogue_length, num_input_features)`` and
-``y`` is an array of shape ``(num_stories, max_dialogue_length, num_bot_features)``.
-The smaller dialogues are padded with ``-1`` for all features, indicating no values for a policy.
+``FullDialogueTrackerFeaturizer`` creates numerical representation of
+stories to feed to a recurrent neural network where the whole dialogue
+is fed to a network and the gradient is backpropagated from all time steps.
+Therefore, ``X`` is an array of shape
+``(num_stories, max_dialogue_length, num_input_features)`` and
+``y`` is an array of shape
+``(num_stories, max_dialogue_length, num_bot_features)``.
+The smaller dialogues are padded with ``-1`` for all features, indicating
+no values for a policy.
 
 2. Max History
 --------------
 
-``MaxHistoryTrackerFeaturizer`` creates an array of previous tracker states for each bot action or utterance, with
-the parameter ``max_history`` defining how many states go into each row in ``X``.
-Deduplication is performed to filter out duplicated turns (bot actions or bot utterances) in terms of their previous states.
-Hence ``X`` has shape ``(num_unique_turns, max_history, num_input_features)`` and ``y`` is an array of shape ``(num_unique_turns, num_bot_features)``.
+``MaxHistoryTrackerFeaturizer`` creates an array of previous tracker
+states for each bot action or utterance, with the parameter
+``max_history`` defining how many states go into each row in ``X``.
+Deduplication is performed to filter out duplicated turns (bot actions
+or bot utterances) in terms of their previous states. Hence ``X``
+has shape ``(num_unique_turns, max_history, num_input_features)``
+and ``y`` is an array of shape ``(num_unique_turns, num_bot_features)``.
 
-For some algorithms a flat feature vector is needed, so ``X`` should be reshaped to ``(num_unique_turns, max_history * num_input_features)``.
-If numeric target class labels are needed instead of one-hot vectors, use ``y.argmax(axis=-1)``.
+For some algorithms a flat feature vector is needed, so ``X``
+should be reshaped to
+``(num_unique_turns, max_history * num_input_features)``. If numeric
+target class labels are needed instead of one-hot vectors, use
+``y.argmax(axis=-1)``.
 
 
 .. include:: ../feedback.inc
-
-.. raw:: html
-   :file: ../livechat.html

docs/api/interpreter.rst

@@ -3,7 +3,7 @@
 Interpreters
 ============
 
-Rasa Core itself does not interpret text. You can use `Rasa NLU <https://rasa.com/docs/nlu/>`_ for this. 
+Rasa Core itself does not interpret text. You can use `Rasa NLU <https://rasa.com/docs/nlu/>`_ for this.
 
 
 .. autoclass:: rasa_core.interpreter.RasaNLUHttpInterpreter
@@ -87,6 +87,3 @@ and entities:
 
 	
 .. include:: ../feedback.inc
-
-.. raw:: html
-   :file: ../livechat.html

docs/api/policy.rst

@@ -15,6 +15,3 @@ A Policy decides what action to take at every step in a dialogue
 
 
 .. include:: ../feedback.inc
-
-.. raw:: html
-   :file: ../livechat.html

docs/api/slots_api.rst

@@ -127,6 +127,3 @@ The Slot base class
 
 
 .. include:: ../feedback.inc
-
-.. raw:: html
-   :file: ../livechat.html

docs/api/tracker.rst

@@ -10,12 +10,9 @@ conversation are received and updated after actions have been executed
 
    .. automethod:: DialogueStateTracker.current_state
    .. automethod:: DialogueStateTracker.current_slot_values
-   .. automethod:: DialogueStateTracker.get_slot    
+   .. automethod:: DialogueStateTracker.get_slot
    .. automethod:: DialogueStateTracker.get_latest_entity_values
    .. automethod:: DialogueStateTracker.copy
 
-
-.. include:: ../feedback.inc
 
-.. raw:: html
-   :file: ../livechat.html
+.. include:: ../feedback.inc

docs/architecture.rst

@@ -9,12 +9,12 @@ responds to a message:
 
 .. image:: _static/images/rasa_arch_colour.png
 
-The steps are: 
+The steps are:
 
 1. The message is received and passed to an ``Interpreter``, which
    converts it into a dictionary including the original text, the intent,
    and any entities that were found.
-2. The ``Tracker`` is the object which keeps track of conversation state. 
+2. The ``Tracker`` is the object which keeps track of conversation state.
    It receives the info that a new message has come in.
 3. The policy receives the current state of the tracker.
 4. The policy chooses which action to take next.

docs/conf.py

@@ -61,6 +61,13 @@
 # The master toctree document.
 master_doc = 'index'
 
+nitpicky = True
+nitpick_ignore = [
+    ('py:class', 'List'),
+    # TODO: remove when https://github.com/sphinx-doc/sphinx/issues/5480 fixed
+    ('py:class', 'Domain'),
+]
+
 # General information about the project.
 project = u'Rasa Core'
 copyright = u'2018, Rasa Technologies GmbH'

docs/connectors.rst

@@ -15,7 +15,7 @@ Currently, there is code for connecting to
 facebook, slack, telegram, mattermost and twilio. If the connection
 you want is missing, this is a great place to start contributing!
 
-If you're testing on your local machine (e.g. not a server), you 
+If you're testing on your local machine (e.g. not a server), you
 will need to use ngrok_. This gives your machine a domain name
 and so that facebook, slack, etc. know where to send messages.
 
@@ -719,5 +719,4 @@ posted this message to the channel:
 
 .. include:: feedback.inc
 
-
-
+

docs/customactions.rst

@@ -116,7 +116,7 @@ three arguments. You can access the values of slots and the latest message
 sent by the user using the ``tracker`` object, and you can send messages
 back to the user with the ``dispatcher`` object, by calling
 ``dispatcher.utter_template``, ``dispatcher.utter_message``, or any other
-:class:`Dispatcher` method.
+:class:`rasa_core.dispatcher.Dispatcher` method.
 
 Details of the ``run`` method:
 

docs/debugging.rst

@@ -5,13 +5,13 @@
 Debugging
 =========
 
-.. note:: 
+.. note::
 
    Wherever you are talking to the bot (command line, slack, facebook, etc), you can
    clear the tracker and start a new conversation by sending the message ``/restart``.
 
 
-To debug your bot, run it on the command line with the ``--debug`` flag. 
+To debug your bot, run it on the command line with the ``--debug`` flag.
 
 For example:
 
@@ -26,12 +26,12 @@ For example:
 .. code-block:: bash
    :linenos:
 
-    Bot loaded. Type a message and press enter: 
+    Bot loaded. Type a message and press enter:
     /greet
     rasa_core.tracker_store - Creating a new tracker for id 'default'.
     rasa_core.processor - Received user message '/greet' with intent '{'confidence': 1.0, 'name': 'greet'}' and entities '[]'
     rasa_core.processor - Logged UserUtterance - tracker now has 2 events
-    rasa_core.processor - Current slot values: 
+    rasa_core.processor - Current slot values:
 
     rasa_core.policies.memoization - Current tracker state [None, {}, {'prev_action_listen': 1.0, 'intent_greet': 1.0}]
     rasa_core.policies.memoization - There is a memorised next action '2'
@@ -47,16 +47,19 @@ or made a mistake when extracting entities. If this is the case, you probably
 want to go and improve your NLU model.
 
 If any slots are set, those will show up in line ``6``.
-and in lines ``9-11`` we can see which policy was used to predict the next action.
-If this exact story was already in the training data and the :class:`MemoizationPolicy`
-is part of the ensemble, this will be used to predict the next action with probability 1.
-
-If all the slot and NLU information is correct but the wrong action is still predicted,
-you should check which policy was used to make the prediction. 
-If the prediction came from the :class:`MemoizationPolicy`, then there is an error in
-your stories. If a probabilistic policy like the :class:`KerasPolicy` was used,
-then your model just made a prediction that wasn't right. In that case 
-it is a good idea to run the bot with interactive learning switched on so you can
+and in lines ``9-11`` we can see which policy was used to
+predict the next action.
+If this exact story was already in the training data and the
+``MemoizationPolicy`` is part of the ensemble, this will be used to predict
+the next action with probability 1.
+
+If all the slot and NLU information is correct but the wrong action
+is still predicted, you should check which policy was used to make
+the prediction. If the prediction came from the ``MemoizationPolicy``,
+then there is an error in your stories. If a probabilistic policy
+like the ``KerasPolicy`` was used, then your model just made a
+prediction that wasn't right. In that case it is a good idea to run
+the bot with interactive learning switched on so you can
 create the relevant stories to add to your training data.
 
 
@@ -98,7 +101,7 @@ create a ``visualize.py`` in ``examples/concertbot`` with the following code:
 
 .. literalinclude:: ../examples/concertbot/visualize.py
 
-Which will create the same image as the previous command. 
+Which will create the same image as the previous command.
 The graph we show here is still very simple, graphs can quickly get very complex.
 
 You can make your graph a little easier to read by replacing the user messages

docs/domains.rst

@@ -34,7 +34,7 @@ defined like this:
                - low
                - medium
                - high
-   
+
 
 :ref:`Here <slot_types>` is the full list of slot types defined by
 Rasa Core, along with syntax for including them in your domain file.