Revise Installation from Source Instructions

[MikeHart85]

Currently, the Installation from Source instructions recommend installing the source via pip install . after cloning it. There is also a paragraph that mentions that you may want to install it differently if you plan on developing Lewis (IE, making changes to source and being able to run it with your changes).

The following improvements could be made to and around that section:

• The "if you want to develop Lewis" section isn't very visible / prominent
• It's also immediately clear in its purpose / difference to the pip install . method
• The link points to the wrong documentation section
• The section it's meant to point to still only recommends pip install ".[dev]" (it's missing the -e option)
• There's no explanation on how to just run the source via python, without deploying a pip package

I also wonder if there's any advantage in recommending pip install . (without -e) at all.

You wind up with a pip installed package of Lewis that looks like a release, but is actually some arbitrary snapshot of master when you happened to clone it (or whatever branch you were on). With -e, at least it also shows the directory it's linked to, which lets you know it's not a normal install. It also won't update automatically if you edit the source, and even running pip install . again will silently "fail" (succeed without doing anything), because it's already installed (you have to add the --upgrade option to get it to really update).

It seems like the -e method makes much more sense if you want to pip install from source. And, as an alternative, if you want to avoid deploying source, you could cd src && python -m lewis.

[MichaelWedel]

The link points to the wrong documentation section

I agree with your points except this one. The link points to the general "developer guide", which I think is fair because the section it links from is one of the most introductory sections (if there is such a word) and it might be useful to read through those other sections as well. That being said, the "abstract" in that section could use a sentence about "developing lewis".

The advantage of pip install . over cd src && python -m lewis is that you don't have to do pip install -r requirements.txt first. Furthermore it allows you to use lewis-control, as opposed to cd src && python lewis/scripts/control.py or something along those lines. Your point about recommending always at least recommending -e when using that method is valid in my opinion.

Furthermore, the last sentence on that page is incorrect as well ("If you decided to install Lewis this way, please be aware that the lewis and lewis-control calls in the other parts of the guide have to be replaced with python lewis.py.").

Maybe it's worthwhile considering to amend/replace this entire section with a "Quickstart" section that many other packages seem to have in their docs. It would just show how to install it, run a simulation, interact with it in various ways (lewis-control, telnet).

[MikeHart85]

The "correct" section I thought it should link to is Developing Lewis (because it's the one that contains the alternate installation/workflow instructions), as opposed to Developer Guide (which is just a section index without the any instructions).

Yes, the cd src && python -m lewis approach is quite limited. The only advantage is that it doesn't result in an installed pip package, so might be worth mentioning as an option for that. Maybe just at the end as a "by the way, if you really need to...".

The -e way is the best, I think. You can use lewis exactly as you would when deployed, but you can also edit the source and see your changes apply immediately. The reason I would not recommend pip install . at all is because I can't think of any advantage over pip install -e ., only disadvantages.

I like the idea of a Quickstart section, but we'll probably need three of them: from Package (User), from Source (Developer) and with Docker (???).

[MichaelWedel]

The "correct" section I thought it should link to is Developing Lewis (because it's the one that contains the alternate installation/workflow instructions), as opposed to Developer Guide (which is just a section index without the any instructions).

You're right, there are no instructions at that specific place. Still, somehow it needs to be clear that these "special steps" are not required for just developing a device. Maybe the link could go away entirely to avoid any of this.

I'd say a Package and Docker Quickstart is enough...for developing there is no "quick start" anyway :)