1110222 - Simplification for the install instructions of mozregression

Status: RESOLVED FIXED

(Testing :: mozregression, defect)

Description

[Julien Pagès (:parkouss)]

Currently install instruction for mozregression (http://mozilla.github.io/mozregression/) seems to me over complicated, especially for windows users.

Why don't we simply ask users to install pip (https://pip.pypa.io/en/latest/installing.html) and then hit

pip install -U mozregression

to install it on every platforms ? We could maybe mention virtualenv. I'm sure these packages are easy to install for GNU/Linuxes and macosX, and we could provide a link for windows users to install python and all these tools all in once (http://www.activestate.com/activepython/downloads).

Comment 1

[Julien Pagès (:parkouss)]

Attachment: updating gh-pages and upgrading with jekyll

I worked quite a bit on a new gh-pages for mozregression.

I completely removed the old pages to make use of jekyll inside github (https://help.github.com/articles/using-jekyll-with-pages/). This allow us to have important documentation written in markdown (far better than raw html for the purpose).

I made a first attempt, and you can see the result here: http://parkouss.github.io/mozregression/

I mainly used the basic layout generated with jekyll, remove unused stuff for us, changed the style and reused old documentation to create it.

There is also some fixes (for example regarding a simplification on installation steps), and a few new things.

Please keep in mind that I am not a natural english speaker (well I am pretty sure you notices that!) so there is probably things that needs to be corrected / rephrased. Also, I'm probably not a really good designer too;

The patch is far beyond the purpose of the bug - but it resolves it.

I did not know jekyll before, and find it pretty simple and useful - specially once the layout have been defined (you just write markdown). I wrote some documentation to indicate how it could be tested locally before pushing changes in the README.md file of the gh-pages branch: https://github.com/parkouss/mozregression/blob/gh-pages/README.md.

If you like the idea, we could use this instead of a readthedocs site. I suppose the big difference will be that we will write markdown instead of rst. But somewhere I think it is a good choice, as we want to document mozregression usage and not internal apis of mozregression (sphinx is pretty good at it). Plus it is integrated in github and the url is already known by users.

Well, have a look at it and tell me what you think. :)

Comment 2

[William Lachance (:wlach)]

Comment on attachment 8547039 [details] [review]
updating gh-pages and upgrading with jekyll

Hey this looks great! I think we should go with it. Definitely I think this approach is better than readthedocs for a project like this.

Just a few things I'd like to see either addressed or discussed before we land this. Feel free to r? me again after updating the PR.

Comment 3

[Julien Pagès (:parkouss)]

I fixed the patches. Still I don't know what to do with the python activestate or mozilla-build choice.

I added a comment on the pull request https://github.com/mozilla/mozregression/pull/169 about this; Tell me your preference, I will update the code if needed. Else I am ready for another review.

Comment 4

[Julien Pagès (:parkouss)]

Well, I had time to improve the web site (http://parkouss.github.io/mozregression/):

- I replaced the usage section with documentation. This new section have a subsection usage, and is intended to have other subsections relative to the documentation (use the new --comand option, etc)
- better style (links, some headers - look in usage page)
- tried it on my phone, and did some fixes so navigation is OK and look and feel is nice when the screen is small

Have a look :)

Comment 5

[Julien Pagès (:parkouss)]

Added documentation to the --command option :

http://parkouss.github.io/mozregression/documentation/automatic-bisection.html

Well, I will stop here with gh-pages until we merge this in. This will need another review and there is already quite some changes. Just as a reminder, last thing do decide is in comment 3.

Comment 6

[Julien Pagès (:parkouss)]

Hi Will,

This NI just to notice you about this bug, so you can think about it when you have some time (start from comment 3).

Comment 7

[William Lachance (:wlach)]

Sorry for the delay on this, I will look at it tomorrow.

Comment 8

[William Lachance (:wlach)]

Comment on attachment 8547039 [details] [review]
updating gh-pages and upgrading with jekyll

This looks great, I have some minor suggestions which I included in the PR. Feel free to merge after they're addressed. :)

Comment 9

[Julien Pagès (:parkouss)]

Great, fixed and merged!