[bloodhound-core] 13/14: Updates to setup advice

[gj...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

gjm pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/bloodhound-core.git

commit d5f0a61e2836ce8b1c8aa6b7bce134264ae8c003
Author: Gary Martin <gj...@apache.org>
AuthorDate: Tue Jan 14 02:06:28 2020 +0000

    Updates to setup advice
---
 README.md | 112 ++++++++++++++++++++++++++++++++++++--------------------------
 1 file changed, 65 insertions(+), 47 deletions(-)

diff --git a/README.md b/README.md
index d3f6549..f0b6e39 100644
--- a/README.md
+++ b/README.md
@@ -1,61 +1,67 @@
 # New Bloodhound
 
-## Requirements
+## Getting the Bloodhound Code:
 
-### Python
+There is a reasonable chance that you are reading these instructions from a
+copy of the source code that you have already placed on the computer that you
+wish to install on. If this is the case you can skip on to the next section.
 
-Bloodhound core is currently written in Python3. It should be possible to
-install and run the core successfully with Python 3.6 or newer. You may
-find that versions from Python 3.4 work but this is not currently tested
-and it is possible that Python features from newer versions may sneak in.
+While in early development, the alternatives for getting the code include
+checking out from [Subversion] with the following command:
 
-If you do not already have an appropriate version of Python installed, you
-may wish to follow instructions for your platform here:
+```
+svn checkout https://svn.apache.org/repos/asf/bloodhound/branches/bh_core_experimental/ bloodhound
+```
 
-  https://docs.python-guide.org/starting/installation/
+or cloning with [Git] from the [Apache Bloodhound Github mirror] - the command
+below should also check out the appropriate branch:
 
-### Pipenv
+```
+git clone --branch bh_core_experimental https://github.com/apache/bloodhound.git
+```
 
-Pipenv is used for looking after Python package dependencies and virtual
-environment management.
+With the commands as specified, both will place the code in the `bloodhound`
+directory.
 
-If you already have the `pip` program installed already, installation of
-pipenv can be as simple as
+[Subversion]: https://subversion.apache.org/
+[Git]: https://git-scm.com/
+[Apache Bloodhound mirror]: https://github.com/apache/bloodhound
+[Github]: https://github.com/
 
-```
-pip install --user pipenv
-```
+## Installing Python and Pipenv
 
-For more information on installing and usage of pipenv, see
-https://docs.pipenv.org/.
+Bloodhound core is currently written in [Python 3] and uses [Pipenv] for
+looking after the python based dependencies.
 
-Once pipenv is installed, the final bit of setup ahead of installing the
-rest of the project dependencies is to ensure that you have picked out the
-appropriate version of Python for your environment. For the same directory
-as the `Pipfile` for the project, you should run:
+It should be possible to install and run the core successfully with Python 3.6
+or newer. You may find that versions from Python 3.4 work but this is not
+currently tested and it is possible that Python features from newer versions
+may sneak in.
 
-```
-pipenv --python 3
-```
+The guide at <https://docs.python-guide.org/> gives good instructions for
+installing Python on [Linux][Python on Linux], [MacOS][Python on MacOS] and
+[Windows][Python on Windows].
 
-If you have multiple versions of Python 3 installed, you may need to be
-more specific about the version.
+Further information about pipenv is available at <https://docs.pipenv.org/>.
 
-### Pipfile Specified Requirements
+[Python 3]: https://docs.python.org/3/
+[Pipenv]: https://pipenv.readthedocs.io/en/latest/
+[Python on Linux]: https://docs.python-guide.org/starting/install3/linux/#install3-linux
+[Python on MacOS]: https://docs.python-guide.org/starting/install3/osx/#install3-osx
+[Python on Windows]: https://docs.python-guide.org/starting/install3/win/#install3-windows
 
-With pipenv installed and the Python version selected, the rest of the
-Python based requrements can be installed with the following command from
-the same director as the `Pipfile` for the project:
+## Preparing the Python environment
 
-```
-pipenv install
-```
+It should now be possible to use pipenv to install the rest of the project
+dependencies and bloodhound itself. Note that the exactly required command may
+depend on details like whether you have multiple versions of python available
+but for most cases, the following should work. If in doubt, just be more
+specific about the python version that you intend to use.
 
-Additionally, to run tests described later, you should install the
-development dependencies:
+For the same directory as the `Pipfile` for the project run:
 
 ```
-pipenv install --dev
+pipenv --python 3 install
 ```
 
 ## Setup
@@ -104,27 +110,28 @@ These paths are subject to change.
 Unit tests are currently being written with the standard unittest framework.
 This may be replaced with pytest.
 
-The tests may be run with the following command:
+Running the tests require a little extra setup:
 
 ```
-pipenv run python manage.py test
+pipenv install --dev
 ```
 
-Fixtures for tests when required can be generated with:
+after which the tests may be run with the following command:
 
 ```
-pipenv run python manage.py dumpdata trackers --format=yaml --indent=2 > trackers/fixtures/[fixture-name].yaml
+pipenv run python manage.py test
 ```
 
 ## Integration Tests
 
-Selenium tests currently require that Firefox is installed and `geckodriver` is
-also on the path. One way to do this is (example for 64bit linux distributions):
-
+The [Selenium] tests currently require that Firefox is installed and
+[geckodriver] is also on the path. If you 
 ```
-BIN_LOCATION="$HOME/.local/bin"
 PLATFORM_EXT="linux64.tar.gz"
-TMP_DIR=/tmp
+BIN_LOCATION="$HOME/.local/bin"
+TMP_DIR=/tmp/geckodriver_download
+mkdir -p "$BIN_LOCATION" "$TMP_DIR"
+
 LATEST=$(wget -O - https://github.com/mozilla/geckodriver/releases/latest 2>&1 | awk 'match($0, /geckodriver-(v.*)-'"$PLATFORM_EXT"'/, a) {print a[1]; exit}')
 wget -N -P "$TMP_DIR" "https://github.com/mozilla/geckodriver/releases/download/$LATEST/geckodriver-$LATEST-$PLATFORM_EXT"
 tar -x geckodriver -zf "$TMP_DIR/geckodriver-$LATEST-$PLATFORM_EXT" -O > "$BIN_LOCATION"/geckodriver
@@ -140,3 +147,14 @@ pipenv run python functional_tests.py
 
 There are currently not many tests - those that are there are in place to test
 the setup above and assume that there will be useful tests in due course.
+
+[Selenium]: https://selenium.dev/
+[geckodriver]: https://firefox-source-docs.mozilla.org/testing/geckodriver/
+
+## Development notes:
+
+Fixtures for tests when required can be generated with:
+
+```
+pipenv run python manage.py dumpdata trackers --format=yaml --indent=2 > trackers/fixtures/[fixture-name].yaml
+```