Merge pull request #1281 from RasaHQ/docs_theme

WIP improve quickstart
RasaHQ · Aug 2, 2018 · 0ecffa4 · 0ecffa4
2 parents 92ec05c + 7c5022a
commit 0ecffa4
Show file tree

Hide file tree

Showing 26 changed files with 208 additions and 175 deletions.
diff --git a/.travis.yml b/.travis.yml
@@ -38,10 +38,8 @@ jobs:
   - stage: docs
     if: fork = false AND branch = "master" # forked repository will skip building docs, only master & PRs to it
     install:
-    - pip install sphinx==1.7.5 sphinx-autobuild==0.7.1 sphinxcontrib-programoutput==0.11 nbsphinx==0.3.2 sphinxcontrib-httpdomain==1.5.0
+    - pip install --no-cache-dir -r alt_requirements/requirements_docs.txt
     - pip install git+https://${GITHUB_TOKEN}:x-oauth-basic@github.com/RasaHQ/sphinxcontrib-versioning.git@version_list
-    - pip install https://storage.googleapis.com/docs-theme/rasabaster-0.7.10.tar.gz
-    - pip install -e git://github.com/RasaHQ/sphinx_rtd_theme.git#egg=sphinx_rtd_theme
     - pip install -e .
     - pip list
     script:

diff --git a/alt_requirements/requirements_dev.txt b/alt_requirements/requirements_dev.txt
@@ -1,5 +1,7 @@
 -r requirements_full.txt
 
+-r requirements_docs.txt
+
 # test
 python-coveralls==2.9.1
 pytest-pep8==1.0.6
@@ -13,12 +15,3 @@ mock==2.0.0
 # other
 google-cloud-storage==1.7.0
 azure-storage-blob==1.0.0
-
-# docs
-sphinx==1.5.2
-sphinx-autobuild==0.7.1
-sphinxcontrib-versioning==2.2.1
-sphinxcontrib-programoutput==0.11
-nbsphinx==0.2.18
-https://storage.googleapis.com/docs-theme/rasabaster-0.7.10.1.tar.gz
--e git://github.com/RasaHQ/sphinx_rtd_theme.git#egg=sphinx_rtd_theme
diff --git a/alt_requirements/requirements_docs.txt b/alt_requirements/requirements_docs.txt
@@ -0,0 +1,8 @@
+# docs
+sphinx==1.7.5
+sphinx-autobuild==0.7.1
+sphinxcontrib-programoutput==0.11
+nbsphinx==0.3.2
+sphinxcontrib-httpdomain==1.5.0
+https://storage.googleapis.com/docs-theme/rasabaster-0.7.12.tar.gz
+-e git://github.com/RasaHQ/sphinx_rtd_theme.git#egg=sphinx_rtd_theme
diff --git a/binder/postBuild b/binder/postBuild
@@ -0,0 +1 @@
+python -m spacy download en
diff --git a/binder/requirements.txt b/binder/requirements.txt
@@ -0,0 +1,9 @@
+# Minimum Instal Requirements
+-r ../alt_requirements/requirements_bare.txt
+
+# Spacy Requirements
+-r ../alt_requirements/requirements_spacy_sklearn.txt
+
+# Tensorflow Requirements
+-r ../alt_requirements/requirements_tensorflow_sklearn.txt
+
diff --git a/docs/changelog.rst b/docs/changelog.rst
@@ -1 +1,2 @@
-.. include:: ../CHANGELOG.rst
+:desc: Rasa NLU Changelog
+.. include:: ../CHANGELOG.rst
diff --git a/docs/choosing_pipeline.rst b/docs/choosing_pipeline.rst
@@ -1,3 +1,5 @@
+:desc: Setting up a Rasa NLU pipeline
+
 .. _choosing_pipeline:
 
 Choosing a Pipeline

diff --git a/docs/conf.py b/docs/conf.py
@@ -40,7 +40,9 @@
     'sphinxcontrib.programoutput',
     'sphinxcontrib.httpdomain',
     'rasabaster.button',
-    'rasabaster.card'
+    'rasabaster.card',
+    'rasabaster.copyable',
+    'rasabaster.runnable'
 ]
 
 # Add any paths that contain templates here, relative to this directory.
@@ -145,7 +147,7 @@
 
 # The name for this set of Sphinx documents.
 # "<project> v<release> documentation" by default.
-#html_title = u'rasa_nlu v0.3.0'
+html_title = u''
 
 # A shorter title for the navigation bar.  Default is the same as html_title.
 #html_short_title = None

diff --git a/docs/config.rst b/docs/config.rst
@@ -1,3 +1,4 @@
+:desc: Customizing Your Rasa NLU Configuration
 .. _section_configuration:
 
 Server Configuration

diff --git a/docs/customcomponents.rst b/docs/customcomponents.rst
@@ -1,3 +1,4 @@
+:desc: How to build custom Rasa NLU components
 .. _section_customcomponents:
 
 Custom Components

diff --git a/docs/dataformat.rst b/docs/dataformat.rst
@@ -1,3 +1,4 @@
+:desc: The Rasa NLU Training Data Format
 .. _section_dataformat:
 
 Training Data Format

diff --git a/docs/docker.rst b/docs/docker.rst
@@ -1,3 +1,4 @@
+:desc: Using Rasa NLU with Docker
 .. _section_docker:
 
 Running in Docker

diff --git a/docs/entities.rst b/docs/entities.rst
@@ -1,3 +1,4 @@
+:desc: Entity Extraction with Rasa NLU
 .. _section_entities:
 
 Entity Extraction

diff --git a/docs/evaluation.rst b/docs/evaluation.rst
@@ -1,3 +1,5 @@
+:desc: Evaluating ML models trained with Rasa NLU
+
 .. _section_evaluation:
 
 Evaluating and Improving Models

diff --git a/docs/fallback.rst b/docs/fallback.rst
@@ -1,3 +1,4 @@
+:desc: Fallback and default actions in Rasa
 .. _section_fallback:
 
 Confidence and Fallback Intents

diff --git a/docs/faq.rst b/docs/faq.rst
@@ -1,3 +1,4 @@
+:desc: Rasa NLU: frequently asked questions
 .. _section_faq:
 
 Frequently Asked Questions

diff --git a/docs/http.rst b/docs/http.rst
@@ -1,3 +1,4 @@
+:desc: The Rasa NLU REST API
 .. _section_http:
 
 HTTP API

diff --git a/docs/index.rst b/docs/index.rst
@@ -1,14 +1,14 @@
 
-Language Understanding with Rasa NLU
-====================================
+Rasa NLU: Language Understanding for chatbots and AI assistants
+===============================================================
 
 .. note::
     This is the documentation for version |release| of Rasa NLU. Please make sure you are reading the documentation 
     that matches the version you have installed.
 
 
 
-Rasa NLU is an open-source tool for intent classification and entity extraction. For example, taking a sentence like
+Rasa NLU is an open-source natural language processing tool for intent classification and entity extraction in chatbots. For example, taking a sentence like
 
 .. code-block:: console
 
@@ -27,18 +27,25 @@ and returning structured data like
     }
 
 
-The intended audience is mainly people developing chatbots and voice apps.
+The target audience is developers building chatbots and voice apps.
+
+The main reasons for using open source NLU are that:
+
+- you don't have to hand over all your training data to Google, Microsoft, Amazon, or Facebook.
+- Machine Learning is not one-size-fits all. You can tweak and customize models for your training data.
+- Rasa NLU runs wherever you want, so you don't have to make an extra network request for every message that comes in.
+
 You can read about the advantages of using open source NLU in this `blog post <https://medium.com/rasa-blog/do-it-yourself-nlp-for-bot-developers-2e2da2817f3d>`_ .
-You can see an independent benchmark comparing Rasa NLU to various closed source tools `here <https://drive.google.com/file/d/0B0l-QQUtZzsdVEpaWEpyVzhZQzQ/view>`_. 
+You can see an independent benchmark comparing Rasa NLU to closed source alternatives `here <https://drive.google.com/file/d/0B0l-QQUtZzsdVEpaWEpyVzhZQzQ/view>`_. 
 
 
 .. toctree::
    :maxdepth: 1
    :caption: Getting Started
    :hidden:
 
+   Try It Out <quickstart>
    installation
-   quickstart
 
 
 .. toctree::

diff --git a/docs/installation.rst b/docs/installation.rst
@@ -1,7 +1,12 @@
+:desc: Installing Rasa NLU on Mac, Windows, and Linux
+:meta_image: https://i.imgur.com/nGF1K8f.jpg
+
 .. _section_backends:
 
 Installation
 ============
+
+
 Prerequisites
 ~~~~~~~~~~~~~
 For windows
@@ -14,7 +19,7 @@ Setting up Rasa NLU
 ~~~~~~~~~~~~~~~~~~~
 The recommended way to install Rasa NLU is using pip:
 
-.. code-block:: bash
+.. copyable::
 
     pip install rasa_nlu
 

diff --git a/docs/languages.rst b/docs/languages.rst
@@ -1,3 +1,4 @@
+:desc: Langauges Supported by Rasa NLU
 .. _section_languages:
 
 Language Support

diff --git a/docs/license.rst b/docs/license.rst
@@ -1,6 +1,6 @@
-
+:desc: The Rasa NLU License
 License
 =======
 
 
-.. literalinclude:: ../LICENSE.txt
+.. literalinclude:: ../LICENSE.txt
diff --git a/docs/migrations.rst b/docs/migrations.rst
@@ -1,3 +1,4 @@
+:desc: Updating your Rasa NLU Project to a New Version
 Migration Guide
 ===============
 This page contains information about changes between major versions and

diff --git a/docs/persist.rst b/docs/persist.rst
@@ -1,3 +1,4 @@
+:desc: Persisting Rasa NLU models in the cloud
 .. _section_persistence:
 
 Storing Models in the Cloud

diff --git a/docs/pipeline.rst b/docs/pipeline.rst
@@ -1,3 +1,4 @@
+:desc: Understanding a Rasa NLU Pipeline
 .. _section_pipeline:
 
 Pipeline and Component Configuration

diff --git a/docs/python.rst b/docs/python.rst
@@ -1,3 +1,4 @@
+:desc: How to use Rasa NLU in a Python project
 .. _section_python:
 
 Python API