Merge dcd00d4 into bd5f27f

docs/quickstart/next-steps.rst

@@ -26,40 +26,29 @@ to see a summary of the TODOs again:
 
 Let's have a look at some of them one-by-one and explain what they are for:
 
-1. Creating a ``requirements.txt``: This file is used for pinning the Python
-   dependencies of your instance to specific versions in order to achieve
-   reproducible builds when deploying your instance. You can generate this file
-   in the following fashion (note, this is only for the *instance* and not
-   the *data model*):
-
-   .. code-block:: console
-
-      $ cd my-repository/
-      $ workon my-repository-venv
-      (my-repository-venv)$ pip install --editable .
-      (my-repository-venv)$ pip install pip-tools
-      (my-repository-venv)$ pip-compile
-
-2. Python packages require a ``MANIFEST.in`` which specifies what files are
+1. Python packages require a ``MANIFEST.in`` which specifies what files are
    part of the distributed package. You can update the existing file by running
-   the following commands:
+   the following commands in your site directory:
 
    .. code-block:: console
 
-      (my-repository-venv)$ git init
-      (my-repository-venv)$ git add --all
-      (my-repository-venv)$ pip install --editable .[all]
-      (my-repository-venv)$ check-manifest --update
+      $ git init
+      $ git add --all
+      $ pipenv install --editable .[all]
+      $ pipenv shell  # activate the virtual environment
+      (my-site-venv)$ check-manifest --update
 
-3. Translations configuration (``.tx/config``): You might also want to generate
+2. Translations configuration (``.tx/config``): You might also want to generate
    the necessary files to allow localization of the instance in different
    languages via the `Transifex platform <https://www.transifex.com/>`_:
 
    .. code-block:: console
 
-      (my-repository-venv)$ python setup.py extract_messages
-      (my-repository-venv)$ python setup.py init_catalog -l en
-      (my-repository-venv)$ python setup.py compile_catalog
+      # if you have activated the virtual environment skip `pipenv shell`
+      $ pipenv shell
+      (my-site-venv)$ python setup.py extract_messages
+      (my-site-venv)$ python setup.py init_catalog -l en
+      (my-site-venv)$ python setup.py compile_catalog
 
    Ensure project has been created on Transifex under the my-repository
    organisation.
@@ -68,20 +57,21 @@ Let's have a look at some of them one-by-one and explain what they are for:
 
    .. code-block:: console
 
-      (my-repository-venv)$ pip install transifex-client
+      (my-site-venv)$ pipenv install transifex-client
 
    Push source (.pot) and translations (.po) to Transifex:
 
    .. code-block:: console
 
-      (my-repository-venv)$ tx push --skip --translations
+      # getting: tx ERROR: not enough values to unpack (expected 2, got 1)
+      (my-site-venv)$ tx push --skip --translations
 
    Pull translations for a single language from Transifex
 
    .. code-block:: console
 
       # same error here
-      (my-repository-venv)$ tx pull --language en
+      (my-site-venv)$ tx pull --language en
 
 Testing
 ^^^^^^^
@@ -91,13 +81,15 @@ In order to run tests for the instance, you can run:
 .. code-block:: shell
 
   # Install testing dependencies
-  $ workon my-repository-venv
   # The following makes sure you have the tests dependencies installed
   # if you already installed the instance via .[all] you can skip this install
-  (my-repository-venv)$ pip install --editable .[tests]
-  (my-repository-venv)$ ./run-tests.sh  # will run all the tests...
+  $ pipenv install --editable .[tests]
+  # if you have activated the virtual environment skip `pipenv shell`
+  $ pipenv shell
+  (my-site-venv)$ ./run-tests.sh  # will run all the tests...
   # ...or to run individual tests
-  (my-repository-venv)$ pytest tests/ui/test_views.py
+  # ERROR: not found: /home/dinos/invenio/my-site/tests/ui/test_views.py::test_ping
+  (my-site-venv)$ pytest tests/ui/test_views.py
 
 Documentation
 ^^^^^^^^^^^^^
@@ -107,10 +99,11 @@ In order to build and preview the instance's documentation, you can run the
 
 .. code-block:: shell
 
-  $ workon my-repository-venv
   # The following makes sure you have the docs dependencies installed
   # if you already installed the instance via .[all] you can skip this install
-  (my-repository-venv)$ pip install --editable .[docs]
-  (my-repository-venv)$ python setup.py build_sphinx
+  $ pipenv install --editable .[docs]
+  # if you have activated the virtual environment skip `pipenv shell`
+  $ pipenv shell
+  (my-site-venv)$ python setup.py build_sphinx
 
 Open up ``docs/_build/html/index.html`` in your browser to see the documentation.

docs/quickstart/quickstart.rst

@@ -48,48 +48,37 @@ it as a user package or in the virtualenv we define below.
 
   # Install cookiecutter if it is not already installed
   $ sudo apt-get install cookiecutter
-  # OR, once you have created a virtualenv per the steps below, install it
-  (my-repository-venv)$ pip install --upgrade cookiecutter
-
-
-.. note::
-
-  If you install Cookiecutter in the virtualenv, you will need to activate the
-  virtualenv to be able to use `cookiecutter` on the command-line.
-
-We can now begin. First, let's create a `virtualenv
-<https://virtualenv.pypa.io/en/stable/installation/>`_ using `virtualenvwrapper
-<https://virtualenvwrapper.readthedocs.io/en/latest/install.html>`_ in order to
-sandbox our Python environment for development:
-
-.. code-block:: shell
-
-  $ mkvirtualenv my-repository-venv
+  $ sudo apt-get install pipenv
 
 Now, let's scaffold the instance using the `official cookiecutter template
 <https://github.com/inveniosoftware/cookiecutter-invenio-instance>`_.
 
 .. code-block:: shell
 
-  (my-repository-venv)$ cookiecutter gh:inveniosoftware/cookiecutter-invenio-instance --checkout v3.0
+  $ cookiecutter gh:inveniosoftware/cookiecutter-invenio-instance --checkout v3.1
   # ...fill in the fields...
 
+.. note::  The cookiecutter script will ask you to resolve some TODOs. They are not required for quick start and you
+   can leave TODOs until you follow the :ref:`next_steps` section of this tutorial.
+
+
 Now that we have our instance's source code ready we can proceed with the
 initial setup of the services and dependencies of the project:
 
 .. code-block:: shell
 
   # Fire up the database, Elasticsearch, Redis and RabbitMQ
-  (my-repository-venv)$ cd my-site/
-  (my-repository-venv)$ docker-compose up -d
+  $ cd my-site/
+  $ docker-compose up -d
   Creating network "mysite_default" with the default driver
   Creating mysite_cache_1 ... done
   Creating mysite_db_1    ... done
   Creating mysite_es_1    ... done
   Creating mysite_mq_1    ... done
 
 If the Elasticsearch service fails to start mentioning that it requires more virtual memory,
-see the following fix <https://www.elastic.co/guide/en/elasticsearch/reference/current/docker.html#docker-cli-run-prod-mode>`_.
+see the following `fix <https://www.elastic.co/guide/en/elasticsearch/reference/current/docker.html#docker-cli-run-prod-mode>`_.
+
 
 .. _customize:
 
@@ -103,41 +92,44 @@ instance we will use the `official data model cookiecutter template
 
 .. code-block:: shell
 
-  (my-repository-venv)$ cd ..  # switch back to the parent directory
-  (my-repository-venv)$ cookiecutter gh:inveniosoftware/cookiecutter-invenio-datamodel --checkout v3.0
+  $ cd ..  # switch back to the parent directory
+  $ cookiecutter gh:inveniosoftware/cookiecutter-invenio-datamodel --checkout v3.1
   # ...fill in the fields...
 
 For the purposes of this guide, our data model folder is `my-datamodel`.
 
-Let's also install the data model in our virtualenv:
+Let's also install the data model in our virtualenv (the virtualenv will be created in your current directory):
 
 .. code-block:: shell
 
-  (my-repository-venv)$ pip install -e .
+  $ pipenv install -e ./my-datamodel
 
 
-.. note::
+To activate the virtualenv of the new project, run:
+
+.. code-block:: shell
+
+  $ pipenv shell
 
-   Once you publish your data model somewhere, i.e. the `Python Package Index
-   <https://pypi.org/>`_, you might want to edit your instance's `setup.py` file
-   to add it there as a dependence.
+.. note:: If you have a trouble with creating the virtualenv by pipenv, you can first create the virtualenv, and then
+   run pipenv commands in the created virtual environment.
 
 Now that we have a data model installed we can create database tables and
 Elasticsearch indices:
 
 .. code-block:: shell
 
-  (my-repository-venv)$ cd my-site
-  (my-repository-venv)$ ./scripts/bootstrap
-  (my-repository-venv)$ ./scripts/setup
+  $ cd my-site
+  $ ./scripts/bootstrap
+  $ ./scripts/setup
 
 Run
 ---
 You can now run the necessary processes for the instance:
 
 .. code-block:: shell
 
-  (my-repository-venv)$ ./scripts/server
+  $ ./scripts/server
   * Environment: development
   * Debug mode: on
   * Running on https://127.0.0.1:5000/ (Press CTRL+C to quit)

docs/tutorial-module/develop.rst

@@ -305,23 +305,19 @@ In ``my-datamodel/my-datamodel/jsonschemas/records/custom-record-v1.0.0.json``
 Demo time
 ---------
 
-Let's now see our Invenio module in action when integrated with our Invenio
-instance.
+Let's now see our Invenio module in action when integrated with our Invenio instance.
 
-First we install our new Invenio-Unicorn module. For the purposes of this guide,
-our instance folder is `my-site`, and it's placed in the same root folder as
-`invenio-unicorn`.
+First we install our new Invenio-Unicorn module:
 
 .. code-block:: console
 
-    $ workon my-repository-venv
-    (my-repository-venv)$ pip install --editable .[all]
+    $ pipenv install --editable .[all]
 
 Then, if you've followed the steps in the Quickstart guide, you can go to the
 instance folder, `my-repository`, and start the ``server`` script:
 
-    (my-repository-venv)$ cd ../my-site
-    (my-repository-venv)$ ./scripts/server
+    $ cd ../my-site
+    $ pipenv run ./scripts/server
 
 Then go to ``http://localhost:5000/create`` and you will see the form we just
 created. There are two fields ``Title`` and ``Description``.

docs/tutorial-module/first-commit.rst

@@ -16,24 +16,24 @@ To do so, we will first list our changes and add them to our local git repositor
 
 .. code-block:: console
 
-    (my-module-venv)$ git status
+    $ git status
     # shows all the files that have been modified
-    (my-module-venv)$ git add .
+    $ git add .
     # adds all the modifications
 
 Let's test our changes before we publish them. See :ref:`run-the-tests` for
 more information.
 
 .. code-block:: console
 
-    (my-module-venv)$ ./run-tests.sh
+    $ pipenv run ./run-tests.sh
 
 If it complains about the manifest, it is because we added new files, but we
 didn't register them into the ``MANIFEST.in`` file, so let's do so:
 
 .. code-block:: console
 
-    (my-module-venv)$ check-manifest -u
+    $ pipenv run check-manifest -u
 
 Push the code
 -------------
@@ -42,5 +42,5 @@ a branch created locally, we need to push the branch on GitHub:
 
 .. code-block:: console
 
-    (my-module-venv)$ git commit -am "New form, views and templates"
-    (my-module-venv)$ git push --set-upstream origin dev
+    $ git commit -am "New form, views and templates"
+    $ git push --set-upstream origin dev

docs/tutorial-module/run-n-test.rst

@@ -131,20 +131,20 @@ Now, go into the root directory of your module, and run
 
 .. code-block:: bash
 
-    (my-module-venv)$ git remote add origin URL-OF-YOUR-GITHUB-REPO
+    $ git remote add origin URL-OF-YOUR-GITHUB-REPO
 
 Now, we can commit and push the generated files:
 
 .. code-block:: bash
 
-    (my-module-venv)$ git commit -am "Initial module structure"
-    (my-module-venv)$ git push --set-upstream origin master
+    $ git commit -am "Initial module structure"
+    $ git push --set-upstream origin master
 
 Finally, we create a new branch to develop on it
 
 .. code-block:: bash
 
-    (my-module-venv)$ git checkout -b dev
+    $ git checkout -b dev
 
 Next Step
 ---------