Split the getting-started guide in 3 parts
ClosedPublic
Actions

Authored by douardda on Feb 6 2019, 3:15 PM.

Details

Reviewers

ardumont
vlorentz

Group Reviewers

Reviewers

Commits

rDDOC9e6c2f3a614d: Split the getting-started guide in 3 parts

Summary

a very basic docker-based quick start,
a more advanced developer setup guide (using mixed docker/venv install),
the original manual setup guide.

Diff Detail

Repository

rDDOC Development documentation

Branch

wip

Lint

Lint Skipped

Unit

Unit Tests Skipped

Build Status

Buildable 4142
Build 5457: arc lint + arc unit

Event Timeline

douardda created this revision.Feb 6 2019, 3:15 PM

Herald added a reviewer: Reviewers. · View Herald TranscriptFeb 6 2019, 3:15 PM

Harbormaster completed remote builds in B4028: Diff 3408.Feb 6 2019, 3:15 PM

ardumont added a subscriber: ardumont.Feb 6 2019, 3:17 PM

ardumont added inline comments.

docs/developer-setup.rst
14	containers
51	--with-testing?

ardumont added inline comments.Feb 6 2019, 3:21 PM

docs/developer-setup.rst
63	life
docs/getting-started.rst
27–28	running
39	is that using what you proposed about openapi/swagger (T1510)?

Sounds good!

docs/index.rst
14–16	`start here to get your own Software Heritage`

This revision is now accepted and ready to land.Feb 6 2019, 3:23 PM

Could you add a paragraph in the intro of getting-started.rst to sum up the difference between the three install methods?

Other than that, lgtm!

docs/developer-setup.rst
26–29	indent
65–77	indent + should add a comment about what the eval does
docs/index.rst
14–17	s/on the //

vlorentz accepted this revision.Feb 6 2019, 3:26 PM

ardumont added inline comments.Feb 7 2019, 1:50 PM

docs/developer-setup.rst
66	val is right, i'm not sure what this does.
69	using an environment variable would be good here. Personally, I'm defining an SWH_ENVIRONMENT_HOME in my .sh routines (here its value would be ~/swh-environment)

ardumont added inline comments.Feb 7 2019, 1:54 PM

docs/developer-setup.rst
65	WORKON_HOME? from virtualenvwrapper's documentation [1], it's defining the WORKON_HOME variable, not VIRTUAL_ENV. [1] https://virtualenvwrapper.readthedocs.io/en/latest/install.html#shell-startup-file

ardumont added inline comments.Feb 7 2019, 2:04 PM

docs/developer-setup.rst
51	Also we'd like to install tox and pifpaf for running tests. pip install $(./bin/pip-swh-packages --with-testing) tox pifpaf Note: i needed to ask for wheel in the .venv, now i see it's already done by virtualenvwrapper! cool.

I'm a bit puzzled that with so many comments, this diff has been accepted! It should not have been so IMHO.

I'm a bit puzzled that with so many comments, this diff has been accepted! It should not have been so IMHO.

I initially only saw typos (and one missing flag).
It's not something that blocks a merge for me (even if i prefer we integrate without those ;).

As you did not merge it immediately though, i checked again but following the guide this time.
New remarks came.

I could have changed then but it did not occur to me.

rebased and fixes reported by aardumont and vlorentz

Harbormaster completed remote builds in B4142: Diff 3509.Feb 11 2019, 5:30 PM

douardda added inline comments.Feb 11 2019, 5:30 PM

docs/developer-setup.rst
65	Nope, WORKON_HOME is be the directory where virtualenvwrapper looks for known virtual envs. Here we want to amend the postactivate script located in the bin directory of the current virtual env, thus in $VIRTUAL_ENV/bin (VIRTUAL_ENV is defined by venv, not venvwrapper). To be really accurate, this should be $VIRTUAL_ENV/$VIRTUALENVWRAPPER_ENV_BIN_DIR but...
66	This is just the application of ckick's doc: https://click.palletsprojects.com/en/7.x/bashcomplete/#activation
69	I do use the cdproject function to get back to this directory, so I do not really need such a variable. It could be added, but I won't add it now.
docs/getting-started.rst
39	not at all