Improve installation guide #3631

stsewd · 2018-02-18T03:08:07Z

This is my second attend to improve the installation guide (first one #3614), I have take some notes from #3614 (comment), #3614 (comment), #3488 (comment).

I try to reduce the trying to teach how to use for provide useful links and be a little more lineal on the steps. And remove lots of notes that are really necessary, but give the impression of be optional.

Please let me know any issues with the English :)

Closes #2246

stsewd · 2018-02-18T03:09:22Z

docs/install.rst

@@ -3,121 +3,120 @@
 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.


I'm not completely sure about this change, please let me know what you think.

Better, for me.

stsewd · 2018-02-18T03:10:30Z

docs/install.rst

-    Read the Docs does not itself run under Python 3 (though it does support
-    building documentation for Python 3 projects). Please ensure the subsequent
-    steps are performed using Python 2.7.
+    Read the Docs does not full support running under Python 3


The rtd code can run on python3, but I think we are not confident enough (#3570)

I wouldn't advertise any level of Python 3 support until we use it on production, have a running test suite, and bandwidth to response user reports. I think it would be better to keep the old wording or say something like "Python 3 support is planned, PRs welcome."

Yeah, the previous wording was better.

RTD should fully support Python3. There are some core devs that develop using Py3 and it's fine. Although, I'd say that it's not well/fully tested as it should and production runs Py2 yet.

Yup, I don't think there is any reason to scare users into not using py3. We'll be using it in prod as soon as we migrate. I'm not sure I even want to mention that RTD isn't py3 in prod, as I'd rather we get PRs now for py3 incompatibilities.

stsewd · 2018-02-18T03:12:02Z

docs/install.rst

-        CFLAGS=-I/usr/local/opt/libxml2/include/libxml2 \
-        LDFLAGS=-L/usr/local/opt/libxml2/lib \
-        pip install -r requirements.txt
+    * On Ubuntu you can install it using ``sudo apt-get install elasticsearch``


Not really sure if this lines are necessary, since is only for Ubuntu.

stsewd · 2018-02-18T03:13:18Z

docs/install.rst

-.. note::
+    CFLAGS=-I/usr/local/opt/libxml2/include/libxml2 \
+    LDFLAGS=-L/usr/local/opt/libxml2/lib \
+    pip install -r requirements.txt


These is the only non-linear step, but no big deal I think

stsewd · 2018-02-18T03:14:20Z

docs/install.rst

+.. _Python 2.7: http://www.python.org/
+.. _virtualenv: https://virtualenv.pypa.io/en/stable/
+.. _Git: http://git-scm.com/
+.. _`Mercurial`: https://www.mercurial-scm.org/


Ups, a little of inconsistency here

stsewd · 2018-02-18T03:15:14Z

docs/install.rst


-    pip --version
+.. _Python 2.7: http://www.python.org/
+.. _virtualenv: https://virtualenv.pypa.io/en/stable/


Referring to the docs here, instead of pypi page of virtualenv

stsewd · 2018-02-18T03:15:33Z

docs/install.rst


-    pip install --upgrade pip
+Cloning the repository and start Django


Not sure about this title, please help

"Get and Run Read the Docs" ?

I like more that!

stsewd · 2018-02-18T03:17:41Z

docs/install.rst

-    mkdir checkouts
-    cd checkouts
-    git clone https://github.com/rtfd/readthedocs.org.git
+    virtualenv venv


Following the pythonic convention here, virtual env called venv and on the project root (now we have this on the .gitignore :) #3609).

stsewd · 2018-02-18T03:18:11Z

docs/install.rst


-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)::


little warning for common error

stsewd · 2018-02-18T03:20:06Z

docs/install.rst


    python manage.py migrate

-Then please create a superuser account for Django::
+Then create a superuser account for Django::


Not that I do not like it, but I had the feeling that it was optional.

stsewd · 2018-02-18T03:20:30Z

docs/install.rst


    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 a test projects::


Now, this is optional!

And believe the a on a test projects isn't necessary.

stsewd · 2018-02-18T03:21:40Z

docs/install.rst

-with the name of any added project::
+While the webserver 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::


I forgot to include on the PR, but this closes #2246

Seems that this command doesn't work #3696

After #3696 (comment), is really necessary show this command here? Probably is better to have a section explaining the full set of management commands for development.

stsewd · 2018-02-18T03:24:42Z

docs/install.rst


    python manage.py update_repos pip

+Further steps


With this steps you can start the server and do a build (sometimes is required to install some more dependencies for generating the pdf), but I feel that these others docs are connected on some way

I'd say that this section should go after "What's available".

Also, in the section "What's available" you could include a note mentioning that pdf generation is not covered here or to do that it's required to use the docker image.

humitos

Nice! I left some comments to consider.

humitos · 2018-02-20T15:30:46Z

docs/install.rst

-    Read the Docs does not itself run under Python 3 (though it does support
-    building documentation for Python 3 projects). Please ensure the subsequent
-    steps are performed using Python 2.7.
+    Read the Docs does not full support running under Python 3


Yeah, the previous wording was better.

RTD should fully support Python3. There are some core devs that develop using Py3 and it's fine. Although, I'd say that it's not well/fully tested as it should and production runs Py2 yet.

humitos · 2018-02-20T15:43:41Z

docs/install.rst

-.. _Git: http://git-scm.com/
-.. _Homebrew: http://brew.sh/
-.. _Elasticsearch: https://www.elastic.co/products/elasticsearch
-.. _PostgreSQL: https://www.postgresql.org/


Why did you remove py2.7, and postgresql here? RTD depends on them, right?

Or, at least Py2.7 since SQLite is used instead of PostgreSQL.

I didn't, there are just moved down :) the diff doesn't help too much p:

But, I think I forgot postgres

@humitos redis is mandatory for the installation?

We have some code that checks redis queue length directly, but i'd like to eventually remove that check completely.

humitos · 2018-02-20T15:48:41Z

docs/install.rst


-    Users of other Linux distributions may need to install the equivalent
-    packages, depending on their system configuration.
+If you are having trouble on OS X Mavericks


Mmm... I think the order of the steps are confusing.

Here we are talkinga about the problems you may be having but we didn't run any command yet. These errors could appear while running pip install -r.

So, I like the idea of having these OS heads here, but maybe this one in particular could still be a note after the pip install command. That way, if you are a Mac user you skip all the other OS section, run that command and in case that it fail you read the note :)

That's better, perhaps I should put that this steps are only for linux for now

humitos · 2018-02-20T15:49:58Z

docs/install.rst


-    Requires Git version >=1.9
+* `Elasticsearch`_ (only if you want full support for searching inside the site)


Elasticsearch needs some more configuration and I wasn't able to configure. I'd say that we should remove this as "depends on" and leave it as a note or remove it completely.

I think this guide is also used for custom installations, right?

humitos · 2018-02-20T15:52:51Z

docs/install.rst


-.. note::
+    * On Ubuntu you can install it using ``sudo apt-get install redis-server``


Why not moving this to the "Ubuntu" section where other packages are installed?

Yeah, you are right, that's a better place

humitos · 2018-02-20T15:54:57Z

docs/install.rst

+.. _Mercurial: https://www.mercurial-scm.org/
+.. _Pip: https://pip.pypa.io/en/stable/
+.. _Homebrew: http://brew.sh/
+.. _Elasticsearch: https://www.elastic.co/products/elasticsearch


Same here. Probably removing this is better to avoid confusion.

humitos · 2018-02-20T16:00:55Z

docs/install.rst


    python manage.py update_repos pip

+Further steps


I'd say that this section should go after "What's available".

humitos · 2018-02-20T16:01:57Z

docs/install.rst


    python manage.py update_repos pip

+Further steps


Also, in the section "What's available" you could include a note mentioning that pdf generation is not covered here or to do that it's required to use the docker image.

humitos · 2018-02-20T16:03:46Z

docs/install.rst


-    pip install --upgrade pip
+Cloning the repository and start Django


"Get and Run Read the Docs" ?

humitos · 2018-02-20T16:09:38Z

docs/install.rst

+
+By now you can trigger builds on your local environment, 
+to encapsulete the build process inside a Docker container,
+see :doc:`development/buildenvironments`.


Also, I think that this page that is linked here should contain a link to another section (a Guide probably) that explains how is the process of creating your own docker image for your user and avoid permission issues.

I mean, a Guide outside the official docs and under /guides/. That's for another PR, though

stsewd · 2018-02-21T16:46:57Z

docs/install.rst

+
+    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.


I added a note about common problems (see #2271 (comment))

stsewd · 2018-02-21T16:48:23Z

docs/install.rst

 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/>`_.

+.. note::
+
+    You can get the verification link from the console where you ran the server.


This is also a common question

stsewd · 2018-02-21T16:51:22Z

@humitos I still have some doubts about removing completely elasticsearch, I think with the current note (is only needed for search) is fine, I mean, people will think the searching no working is a bug.

stsewd · 2018-02-21T16:52:30Z

docs/install.rst

+.. note::
+
+    You can get the verification link from the console where you ran the server.
+
 Importing your docs


I think we can remove this subsection and only have one section

ericholscher · 2018-10-31T12:33:00Z

@stsewd want to resolve the merge conflicts and I can review & commit it. Trying to reduce the number of open PR's we have :)

stsewd · 2018-10-31T14:05:59Z

Got it, working on that

stsewd · 2018-10-31T15:38:42Z

@ericholscher ok, this is ready for re-review.

ericholscher

Looks great. 💯

ericholscher · 2018-10-31T15:55:55Z

docs/install.rst


-        sudo yum install python-devel python-pip libxml2-devel libxslt-devel
+On Ubuntu


I wonder if we could use https://github.com/djungelorm/sphinx-tabs to make this a nicer UI for our users here, instead of having to scroll through all the data for platforms I don't use.

Yeah, that will look better

codecov · 2018-10-31T16:44:10Z

Codecov Report

Merging #3631 into master will increase coverage by 0.05%.
The diff coverage is n/a.

@@            Coverage Diff             @@
##           master    #3631      +/-   ##
==========================================
+ Coverage   76.21%   76.27%   +0.05%     
==========================================
  Files         158      158              
  Lines       10019     9981      -38     
  Branches     1265     1261       -4     
==========================================
- Hits         7636     7613      -23     
+ Misses       2039     2024      -15     
  Partials      344      344

Impacted Files	Coverage Δ
readthedocs/builds/models.py	`75.6% <0%> (-0.38%)`	⬇️
readthedocs/builds/admin.py	`95.83% <0%> (-0.17%)`	⬇️
readthedocs/projects/models.py	`84% <0%> (-0.07%)`	⬇️
readthedocs/profiles/views.py	`86.44% <0%> (ø)`	⬆️
readthedocs/projects/views/private.py	`80.1% <0%> (+1.85%)`	⬆️
readthedocs/builds/forms.py	`95.83% <0%> (+7.95%)`	⬆️

stsewd · 2018-10-31T16:48:18Z

@ericholscher done, it looks like this

ericholscher · 2018-10-31T16:49:28Z

done, it looks like this

💯

humitos · 2018-10-31T17:10:27Z

I love those tabs!

stsewd commented Feb 18, 2018

View reviewed changes

stsewd mentioned this pull request Feb 19, 2018

locally installed readthedocs #2281

Closed

humitos reviewed Feb 20, 2018

View reviewed changes

stsewd commented Feb 21, 2018

View reviewed changes

RichardLitt added the PR: work in progress Pull request is not ready for full review label Feb 21, 2018

stsewd mentioned this pull request Mar 15, 2018

Installation instructions shouldn't mention python 2.7 anymore #3810

Closed

stsewd mentioned this pull request Mar 25, 2018

Build failing and stuck at Triggered state at local installation #3836

Closed

agjohnson added this to the Development improvements milestone Jul 20, 2018

stsewd added 5 commits October 31, 2018 09:39

Improve installation guide

e9c7822

Fix inconsistence

e3f4031

Fix grammar

5368403

Change title

fc89946

Move section

7688697

stsewd added 11 commits October 31, 2018 09:41

Move redis installation to Ubuntu section

466fdc8

Move Mac note to requirements installation step

2aa45e2

Move section

33411e1

Fusion other linux sections

c8621d2

Grammar

df263ba

Fix sentence

dbfc565

Add note about common problem of pdf and epub generation

ff9434e

Add new line

85c2ca7

Add note about the verification email

e3b9aec

Indentation

926862c

Fix rebase changes

c505a5d

stsewd force-pushed the improve-installation-guide branch from 140e09a to c505a5d Compare October 31, 2018 15:13

ericholscher approved these changes Oct 31, 2018

View reviewed changes

Use sphinx-tabs

58d9701

ericholscher merged commit 0f5d979 into readthedocs:master Oct 31, 2018

stsewd deleted the improve-installation-guide branch October 31, 2018 16:58


		pip install --upgrade pip
		Cloning the repository and start Django


		Requires Git version >=1.9
		* `Elasticsearch`_ (only if you want full support for searching inside the site)


		.. note::
		* On Ubuntu you can install it using ``sudo apt-get install redis-server``


		sudo yum install python-devel python-pip libxml2-devel libxslt-devel
		On Ubuntu

Improve installation guide #3631

Improve installation guide #3631

Conversation

stsewd commented Feb 18, 2018 • edited Loading

stsewd Feb 18, 2018 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

stsewd Feb 18, 2018 • edited Loading

Choose a reason for hiding this comment

stsewd Feb 18, 2018 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

humitos left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

stsewd commented Feb 21, 2018

Choose a reason for hiding this comment

ericholscher commented Oct 31, 2018

stsewd commented Oct 31, 2018

stsewd commented Oct 31, 2018

ericholscher left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

codecov bot commented Oct 31, 2018 • edited Loading

Codecov Report

stsewd commented Oct 31, 2018

ericholscher commented Oct 31, 2018

humitos commented Oct 31, 2018

stsewd commented Feb 18, 2018 •

edited

Loading

stsewd Feb 18, 2018 •

edited

Loading

stsewd Feb 18, 2018 •

edited

Loading

stsewd Feb 18, 2018 •

edited

Loading

codecov bot commented Oct 31, 2018 •

edited

Loading