Add a system overview section on the landing page #867 #897

gaborbernat · 2018-07-10T10:26:51Z

I find we lack a quick two-minute high-level overview of what tox is. This should help new people quickly understand easier what tox actually does and expose common gotchas.

See output at https://tox-gaborbernat.readthedocs.io/en/general/#system-overview.

Resolves #867.

codecov · 2018-07-10T10:35:07Z

Codecov Report

Merging #897 into master will not change coverage.
The diff coverage is n/a.

@@           Coverage Diff           @@
##           master     #897   +/-   ##
=======================================
  Coverage   92.61%   92.61%           
=======================================
  Files          12       12           
  Lines        2330     2330           
  Branches      409      409           
=======================================
  Hits         2158     2158           
  Misses        109      109           
  Partials       63       63

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 95f5476...9540e26. Read the comment docs.

obestwalter · 2018-07-10T11:37:09Z

Oh good, this would also address where we started discussing these things: #478.

What should be covered though in the explanation is, that the visualized default flow is highly configurable (e.g. you could not build a package and you could also switch off installing the package (and use tox in a setup.py less project) or you could install a devlopment version.

I have no idea yet how and where this should be visualized/documented, but I think it should definitely be part of a high level overview to make clear that tox can do much more than the standard flow.

gaborbernat · 2018-07-10T11:39:19Z

I know, and if you read the explanation for the phases you can see I pointed out clearly where things change behaviour. I updated the diagram to emphasize the optional phases.

obestwalter · 2018-07-10T12:16:40Z

I have to admit that I did not read very carefully on the first go, I will have a closer look tonight and might have some ideas for improvments.

gaborbernat · 2018-07-11T09:26:38Z

@obestwalter did you manage to get to this? thanks!

obestwalter · 2018-07-11T09:39:06Z

Hi @gaborbernat, I will be able to dedicate this friday to tox properly and try to catch up then.

obestwalter · 2018-07-11T09:40:10Z

BTW - did you watch the video? What do you think about us trying to apply this to the tox documentation?

gaborbernat · 2018-07-11T09:41:56Z

I did not watch the video but was there in the audience. It makes some good points. As far as our project goes I think we just need to have a different page for the plugins.

obestwalter · 2018-07-11T09:48:38Z

I think I will take the friday to have a proper look at our existing docs and go from there.

obestwalter · 2018-07-17T15:47:56Z

doc/index.rst

+
+..
+    The above image raw can be found and edited by using the toxdevorg Google role account under
+    https://www.lucidchart.com/documents/edit/5d921f32-f2e1-4618-a265-7f9e30503dc6/0


That's a very good idea.

obestwalter · 2018-07-17T15:55:44Z

doc/index.rst

+
+3. **environment** - for each tox environment (e.g. ``py27``, ``py36``) do:
+
+    1. **environment creation**: create a fresh environment, by default Python virtual environments


How about shortening that to:

create a fresh environment. By default virtualenv_ is used.

An maybe we could also mention this here?

To use `venv <https://docs.python.org/3/library/venv.html>`_ `pip install tox-venv` additionally to tox.

I prefer having it as phase names, to help new users grasp tox run concepts. Hence I still think environment creation is better. Again let's only discuss the built-in capabilities, so no plugins please.

Sorry if that wasn't clear - I wasn't referring to the phase name, but to the explanation after that. Basically to shorten the first sentence and add the replacement info via plugin there as well (but I am not sure, if that is not overloading that part).

obestwalter · 2018-07-17T16:03:36Z

doc/index.rst

+    means Python 2.7 and the ``basepython`` configuration value) and the current operating system
+    ``PATH`` value. This step is done at first run only (or when :confval:`basepython` value
+    changes) and re-used at subsequent runs, unless the user requests explicitly recreating this
+    by passing in the ``-r`` flag.


A bit more handwavy but maybe sufficient here?

This is created at first run only to be re-used at subsequent runs. If certain aspects of the project change, a re-creation of the environment is automatically triggered. To force the recreation (e.g. when changes weren't properly picked up), tox can be invoked with ``-r``/``--recreate``.

I'll use most of it other than the (e.g. when changes weren't properly picked up). Some changes are not tracked, but I don't think that warrants it being stated not properly.

obestwalter · 2018-07-17T16:05:59Z

doc/index.rst

+    By default ``pip`` is used to install packages, however one can customise this via
+    :confval:`install_command`. Note ``pip`` will not update project dependencies (specified either
+    in the ``install_requires`` or the ``extras`` section of the ``setup.py``) if any version already
+    exists in the virtual environment; therefore we recommend to recreate your environments entirely


"entirely" is not necessary here (and maybe even potentially confusing?), as there is no way to recreate the environment partially.

will dop entirely

obestwalter · 2018-07-17T16:07:46Z

doc/index.rst

+    exists in the virtual environment; therefore we recommend to recreate your environments entirely
+    whenever your project dependencies change.
+
+    3. **commands**: run one by one the specified commands. Whenever the exit code of any of them


How about:

run the specified commands in the specified order.

obestwalter · 2018-07-17T16:09:22Z

doc/index.rst

+
+    3. **commands**: run one by one the specified commands. Whenever the exit code of any of them
+    is not zero stop, and mark the environment failed. Note, starting a command with a single dash
+    character means ignore exit code.


Or:

To ignore the exit code of a command, a dash can be prefixed to the command.

obestwalter · 2018-07-17T16:11:49Z

doc/index.rst

+      ERROR:   py36: commands failed
+
+    Only if all environments finished with success will the exit code of tox be success. In this
+    case you'll also see the message ``congratulations :)``.


or:

Only if all environments ran successfully tox will return `0` (success). In this case you'll also see the message ``congratulations :)``.

obestwalter · 2018-07-17T16:17:18Z

doc/index.rst

+environment variables not specified via :confval:`passenv`. Furthermore, it will also alter the
+``PATH`` variable so that your commands resolve first and foremost within the current active
+tox environment. It's possible to fallback to executables outside of this, however these need to
+be explicitly enabled via the :confval:`whitelist_external` configuration variable.


This is not quite accurate: tox uses whatever is available, but will warn when it was not expllicitly whitelisted.

How about:

In general all executables in the path are available in ``commands``, but tox will emit a warning if it was not explicitly allowed via :confval:`whitelist_external`.

Includes a flow diagram of tox.

gaborbernat added feature:new something does not exist yet, but should area:documentation needs:review somebody who thinks they know what they are doing should have a look at this level:easy rought estimate that this might be quite easy to implement labels Jul 10, 2018

gaborbernat added this to the 3.2 milestone Jul 10, 2018

gaborbernat assigned obestwalter, nicoddemus and asottile Jul 10, 2018

gaborbernat requested review from obestwalter, nicoddemus and asottile July 10, 2018 10:26

gaborbernat force-pushed the master branch 5 times, most recently from af63a7d to cb3d244 Compare July 11, 2018 09:19

gaborbernat force-pushed the master branch from cb3d244 to 13b072f Compare July 11, 2018 09:29

gaborbernat force-pushed the master branch 4 times, most recently from 80d369c to c4923ca Compare July 11, 2018 10:08

gaborbernat force-pushed the master branch 10 times, most recently from 74add49 to bb4a94c Compare July 11, 2018 17:15

asottile force-pushed the master branch from cc3d3e6 to 95f5476 Compare July 17, 2018 14:26

obestwalter requested changes Jul 17, 2018

View reviewed changes

gaborbernat added 2 commits July 17, 2018 17:29

Add a system overview section on the landing page #867

6bfa948

Includes a flow diagram of tox.

PR review adjustment

9540e26

obestwalter approved these changes Jul 17, 2018

View reviewed changes

gaborbernat merged commit b6bcd27 into tox-dev:master Jul 17, 2018

gaborbernat deleted the general branch July 19, 2018 15:13

asottile removed their assignment Feb 9, 2020

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add a system overview section on the landing page #867 #897

Add a system overview section on the landing page #867 #897

gaborbernat commented Jul 10, 2018 •

edited

Loading

codecov bot commented Jul 10, 2018 •

edited

Loading

obestwalter commented Jul 10, 2018

gaborbernat commented Jul 10, 2018 •

edited

Loading

obestwalter commented Jul 10, 2018

gaborbernat commented Jul 11, 2018

obestwalter commented Jul 11, 2018 •

edited

Loading

obestwalter commented Jul 11, 2018

gaborbernat commented Jul 11, 2018

obestwalter commented Jul 11, 2018

obestwalter Jul 17, 2018

obestwalter Jul 17, 2018

gaborbernat Jul 17, 2018 •

edited

Loading

obestwalter Jul 17, 2018

obestwalter Jul 17, 2018

gaborbernat Jul 17, 2018

obestwalter Jul 17, 2018

gaborbernat Jul 17, 2018

obestwalter Jul 17, 2018

obestwalter Jul 17, 2018

obestwalter Jul 17, 2018

obestwalter Jul 17, 2018


		3. environment - for each tox environment (e.g. ``py27``, ``py36``) do:

		1. environment creation: create a fresh environment, by default Python virtual environments

Add a system overview section on the landing page #867 #897

Add a system overview section on the landing page #867 #897

Conversation

gaborbernat commented Jul 10, 2018 • edited Loading

codecov bot commented Jul 10, 2018 • edited Loading

Codecov Report

obestwalter commented Jul 10, 2018

gaborbernat commented Jul 10, 2018 • edited Loading

obestwalter commented Jul 10, 2018

gaborbernat commented Jul 11, 2018

obestwalter commented Jul 11, 2018 • edited Loading

obestwalter commented Jul 11, 2018

gaborbernat commented Jul 11, 2018

obestwalter commented Jul 11, 2018

Choose a reason for hiding this comment

Choose a reason for hiding this comment

gaborbernat Jul 17, 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

gaborbernat commented Jul 10, 2018 •

edited

Loading

codecov bot commented Jul 10, 2018 •

edited

Loading

gaborbernat commented Jul 10, 2018 •

edited

Loading

obestwalter commented Jul 11, 2018 •

edited

Loading

gaborbernat Jul 17, 2018 •

edited

Loading