Merge pull request #3631 from stsewd/improve-installation-guide

Improve installation guide

docs/.rstcheck.cfg

@@ -1,4 +1,4 @@
 [rstcheck]
-ignore_directives=automodule,http:get
+ignore_directives=automodule,http:get,tabs,tab
 ignore_roles=djangosetting,setting
 ignore_messages=(Duplicate implicit target name: ".*")|(Hyperlink target ".*" is not referenced)

docs/conf.py

@@ -27,6 +27,7 @@
     'sphinxcontrib.httpdomain',
     'djangodocs',
     'doc_extensions',
+    'sphinx_tabs.tabs',
 ]
 templates_path = ['_templates']
 

docs/install.rst

@@ -1,113 +1,113 @@
 Installation
 ============
 
-Here is a step by step plan on how to install Read the Docs.
+Here is a step by step guide on how to install Read the Docs.
 It will get you to a point of having a local running instance.
 
+Requirements
+------------
 
-First, obtain `Python 3.6`_ and virtualenv_ if you do not already have them. Using a
-virtual environment will make the installation easier, and will help to avoid
-clutter in your system-wide libraries. You will also need Git_ in order to
-clone the repository. If you plan to import Python 2.7 project to your RTD then you'll
-need to install Python 2.7 with virtualenv in your system as well.
+First, obtain `Python 3.6`_ and virtualenv_ if you do not already have them.
+Using a virtual environment is strongly recommended,
+since it will help you to avoid clutter in your system-wide libraries.
 
+Additionally Read the Docs depends on:
 
-.. _Python 3.6: http://www.python.org/
-.. _virtualenv: http://pypi.python.org/pypi/virtualenv
-.. _Git: http://git-scm.com/
-.. _Homebrew: http://brew.sh/
-.. _Elasticsearch: https://www.elastic.co/products/elasticsearch
-.. _PostgreSQL: https://www.postgresql.org/
-.. _Redis: https://redis.io/
-
-.. note::
+* `Git`_ (version >=2)
+* `Mercurial`_ (only if you need to work with mercurial repositories)
+* `Pip`_ (version >1.5)
+* `Redis`_
+* `Elasticsearch`_ (only if you want full support for searching inside the site)
 
-    Requires Git version >=2
+    * Ubuntu users could install this package by following :doc:`/custom_installs/elasticsearch`.
 
 .. note::
 
-    If you are having trouble on OS X Mavericks (or possibly other versions of
-    OS X) with building ``lxml``, you probably might need to use Homebrew_
-    to ``brew install libxml2``, and invoke the install with::
+    If you plan to import Python 2 projects to your RTD,
+    then you'll need to install Python 2 with virtualenv in your system as well.
 
-        CFLAGS=-I/usr/local/opt/libxml2/include/libxml2 \
-        LDFLAGS=-L/usr/local/opt/libxml2/lib \
-        pip install -r requirements.txt
+In order to get all the dependencies successfully installed,
+you need these libraries.
 
-.. note::
+.. tabs::
+
+   .. tab:: Mac OS
 
-    Linux users may find they need to install a few additional packages
-    in order to successfully execute ``pip install -r requirements.txt``.
-    For example, a clean install of Ubuntu 14.04 LTS will require the
-    following packages::
+      If you are having trouble on OS X Mavericks
+      (or possibly other versions of OS X) with building ``lxml``,
+      you probably might need to use Homebrew_ to ``brew install libxml2``,
+      and invoke the install with::
+      
+          CFLAGS=-I/usr/local/opt/libxml2/include/libxml2 \
+          LDFLAGS=-L/usr/local/opt/libxml2/lib \
+          pip install -r requirements.txt
 
-        sudo apt-get install build-essential
-        sudo apt-get install python-dev python-pip python-setuptools
-        sudo apt-get install libxml2-dev libxslt1-dev zlib1g-dev
+   .. tab:: Ubuntu
 
-    CentOS/RHEL 7 will require::
+      Install::
 
-        sudo yum install python-devel python-pip libxml2-devel libxslt-devel
+         sudo apt-get install build-essential
+         sudo apt-get install python-dev python-pip python-setuptools
+         sudo apt-get install libxml2-dev libxslt1-dev zlib1g-dev
 
-    Users of other Linux distributions may need to install the equivalent
-    packages, depending on their system configuration.
+      If you don't have redis installed yet, you can do it with::
+         
+         sudo apt-get install redis-server
 
-.. note::
-
-   If you want full support for searching inside your Read the Docs
-   site you will need to install Elasticsearch_.
+   .. tab:: CentOS/RHEL 7
 
-   Ubuntu users could install this package by following :doc:`/custom_installs/elasticsearch`.
-
-.. note::
+      Install::
 
-   Besides the Python specific dependencies, you will also need Redis_.
+         sudo yum install python-devel python-pip libxml2-devel libxslt-devel
 
-   Ubuntu users could install this package as following::
+   .. tab:: Other OS
 
-        sudo apt-get install redis-server
+      On other operating systems no further dependencies are required,
+      or you need to find the proper equivalent libraries.
 
 
-You will need to verify that your pip version is higher than 1.5 you can do this as such::
-
-    pip --version
+.. _Python 3.6: http://www.python.org/
+.. _virtualenv: https://virtualenv.pypa.io/en/stable/
+.. _Git: http://git-scm.com/
+.. _Mercurial: https://www.mercurial-scm.org/
+.. _Pip: https://pip.pypa.io/en/stable/
+.. _Homebrew: http://brew.sh/
+.. _Elasticsearch: https://www.elastic.co/products/elasticsearch
+.. _Redis: https://redis.io/
 
-If this is not the case please update your pip version before continuing::
 
-    pip install --upgrade pip
+Get and run Read the Docs
+-------------------------
 
-Once you have these, create a virtual environment somewhere on your disk, then
-activate it::
+Clone the repository somewhere on your disk and enter to the repository::
 
-    virtualenv rtd
-    cd rtd
-    source bin/activate
+    git clone https://github.com/rtfd/readthedocs.org.git
+    cd readthedocs.org
 
-Create a folder in here, and clone the repository::
+Create a virtual environment and activate it::
 
-    mkdir checkouts
-    cd checkouts
-    git clone https://github.com/rtfd/readthedocs.org.git
+    virtualenv venv
+    source venv/bin/activate
 
-Next, install the dependencies using ``pip`` (included inside of virtualenv_)::
+Next, install the dependencies using ``pip``
+(make sure you are inside of the virtual environment)::
 
-    cd readthedocs.org
     pip install -r requirements.txt
 
-This may take a while, so go grab a beverage. When it's done, build your
-database::
+This may take a while, so go grab a beverage.
+When it's done, build the database::
 
     python manage.py migrate
 
-Then please create a superuser account for Django::
+Then create a superuser account for Django::
 
     python manage.py createsuperuser
 
 Now let's properly generate the static assets::
 
     python manage.py collectstatic
 
-By now, it is the right time to load in a couple users and a test project::
+Now you can optionally load a couple users and test projects::
 
     python manage.py loaddata test_data
 
@@ -120,35 +120,56 @@ By now, it is the right time to load in a couple users and a test project::
     create an ``EmailAddress`` entry for the user, then you can use ``shell_plus`` to
     update the object with ``primary=True``, ``verified=True``.
 
-Finally, you're ready to start the webserver::
+Finally, you're ready to start the web server::
 
     python manage.py runserver
 
-Visit http://127.0.0.1:8000/ in your browser to see how it looks; you can use
-the admin interface via http://127.0.0.1:8000/admin (logging in with the
-superuser account you just created).
+Visit http://127.0.0.1:8000/ in your browser to see how it looks;
+you can use the admin interface via http://127.0.0.1:8000/admin
+(logging in with the superuser account you just created).
 
-For builds to properly kick off as expected, it is necessary the port
-you're serving on (i.e. ``runserver 0.0.0.0:8080``) match the port defined
-in ``PRODUCTION_DOMAIN``. You can utilize ``local_settings.py`` to modify this.
-(By default, it's ``localhost:8000``)
+For builds to properly work as expected,
+it is necessary the port you're serving on
+(i.e. ``python manage.py runserver 0.0.0.0:8080``)
+match the port defined in ``PRODUCTION_DOMAIN``.
+You can use ``readthedocs/settings/local_settings.py`` to modify this
+(by default, it's ``localhost:8000``).
 
-While the webserver is running, you can build documentation for the latest version of
-a project called 'pip' with the ``update_repos`` command.  You can replace 'pip'
-with the name of any added project::
+While the web server is running,
+you can build the documentation for the latest version of any project using the ``update_repos`` command.
+For example to update the ``pip`` repo::
 
     python manage.py update_repos pip
 
+.. note::
+
+    If you have problems building successfully a project,
+    probably is because some missing libraries for ``pdf`` and ``epub`` generation.
+    You can uncheck this on the advanced settings of your project.
+
 What's available
 ----------------
 
 After registering with the site (or creating yourself a superuser account),
 you will be able to log in and view the `dashboard <http://localhost:8000/dashboard/>`_.
 
 Importing your docs
-^^^^^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~~~~~
 
 One of the goals of readthedocs.org is to make it easy for any open source developer to get high quality hosted docs with great visibility!
 Simply provide us with the clone URL to your repo, we'll pull your code, extract your docs, and build them!
+
 We make available a post-commit webhook that can be configured to update the docs whenever you commit to your repo.
-See :doc:`/intro/import-guide` to learn more.
+See our :doc:`/intro/import-guide` page to learn more.
+
+Further steps
+-------------
+
+By now you can trigger builds on your local environment, 
+to encapsulate the build process inside a Docker container,
+see :doc:`development/buildenvironments`.
+
+For building this documentation,
+see :doc:`docs`.
+
+And for setting up for the front end development, see :doc:`development/standards`.

requirements/pip.txt

@@ -5,6 +5,7 @@ virtualenv==16.0.0
 docutils==0.14
 Sphinx==1.7.8
 sphinx_rtd_theme==0.4.1
+sphinx-tabs==1.1.7
 # Required to avoid Transifex error with reserved slug
 # https://github.com/sphinx-doc/sphinx-intl/pull/27
 git+https://github.com/agjohnson/sphinx-intl.git@7b5c66bdb30f872b3b1286e371f569c8dcb66de5#egg=sphinx-intl