diff --git a/handbook/computing/basiclaptop.html b/handbook/computing/basiclaptop.html index afbc7c59f..f52ac5b39 100644 --- a/handbook/computing/basiclaptop.html +++ b/handbook/computing/basiclaptop.html @@ -19,7 +19,7 @@
  • Edit the cave description and entrance description text for existing caves
  • Create entirely new caves in the system by filling out online forms -[more details on cave data and survey maintenance are in the data maintenance manual] +

    Documentation on how to actually do these things are in the data maintenance manual.

    And using email to send the results to an expo nerd, you can:

    -

    and familiarise yourself with the directory structure on the expo server, which we will be duplicating (partly) as docmented in The Expo Server. We are not here doing a full install of all the software and scripts on the server, just the minimum to run, test and debug troggle on django. +

    and familiarise yourself with the directory structure on the expo server, which we will be duplicating (partly) as docmented in The Expo Server. We are not here doing a full install of all the software and scripts on the server, just the minimum to run, test and debug troggle on Django.

    WSL on Windows

    The standard documentation for Ubuntu or debian below all works, but you should first skim the @@ -54,7 +54,7 @@ sudo ln -s pip3 pip

    You will also definitely need sqlite3 even if you are planning to use another database. Sqlite3 is used by the test harness system.

    Note that when you install survex it installs a shed load of packages that it needs. -

    We do not install django at this point. We will be installing django in a separate virtual +

    We do not install Django at this point. We will be installing Django in a separate virtual environment (a 'venv'), not in the main linux system.

    @@ -82,15 +82,15 @@ ls -tlA expo django logo

    The important point to note here is that unless you are doing something fairly trivial, or you are a git genius, - it is sensible to set up a python virtual environments to hold duplicate copies of both troggle and django code. + it is sensible to set up a python virtual environments to hold duplicate copies of both troggle and Django code. Then you will be able to check very quickly that your edited version of troggle runs with old, current - and pre-release versions of python and of django; - and you will more easily be able to manage problems with incompatible versions of django plugins as installing and upgrading the dependent packages is very fast. + and pre-release versions of python and of Django; + and you will more easily be able to manage problems with incompatible versions of Django plugins as installing and upgrading the dependent packages is very fast.

    Installing a venv

    We set up - a venv specifically for python 3.7 (which is the standard version on our server which is running unmodified Buster (debian v10) and django 2.2.19. See the standard python documentation on venv for python 3.7.12. You can upgrade the version of python installed within pip venv but not downgrade. So get that first venv installed right by explicitly stating the python version to create it python3.7 -m venv py37d22. + a venv specifically for python 3.7 (which is the standard version on our server which is running unmodified Buster (debian v10) and Django 2.2.19. See the standard python documentation on venv for python 3.7.12. You can upgrade the version of python installed within pip venv but not downgrade. So get that first venv installed right by explicitly stating the python version to create it python3.7 -m venv py37d22. Note that we are creating it as a sibling folder to /expoweb/ . Note also that up to now we have been using 'sudo ..' but for installing things inside the venv we do not use 'sudo ..': 

    cd ~
 cd ../expo
@@ -99,12 +99,12 @@ cd py37d22
 source bin/activate
 pip list -o

    The last command lists the default packages installed in the venv. This is for comparison later, after we -have installed troggle, django and dependencies. You will get a warning that you have an out of date version of pipbut this is as we want: we are using a version of pip appropriate for the older version of python within +have installed troggle, Django and dependencies. You will get a warning that you have an out of date version of pipbut this is as we want: we are using a version of pip appropriate for the older version of python within the venv. troggle logo

    Installing the troggle dependencies

    -

    The first time you do this on a new machine you can't complete the pip installation of django as you have not yet got the +

    The first time you do this on a new machine you can't complete the pip installation of Django as you have not yet got the dependencies appropriate for troggle - because you have not yet cloned the troggle repo. So the first time it is easiest to just create requirements.txt yourself with a text editor. Without using git yourself, you can get the file from the website at requirements.txt. If you have already cloned all the repos, then just copy it. 

    cp ../troggle/requirements.txt .
    where requirements.txt (note the capitalisation of the listed packages) is: @@ -116,7 +116,7 @@ Pillow==5.4.1 pytz==2019.1 sqlparse==0.2.4 Unidecode==1.0.23 -This will pick up the latest django 2.2.x available, but all the other dependencies are pinned. These +This will pick up the latest Django 2.2.x available, but all the other dependencies are pinned. These dependencies are as-standard on debian Buster (10) and you will want to experiment with upgrading them for Bullseye (v11).

    Once you have the file, install the listed dependencies like this: @@ -131,15 +131,15 @@ see /prospecting_guide/) tinymce is the wysiwyg in-browser editor (disabled pending reinstatement) -

    This is also documented in the updating django for troggle page -where it describes upgrading and testing with later versions of django. +

    This is also documented in the updating Django for troggle page +where it describes upgrading and testing with later versions of Django.

    If you have not used pip before, read this

    Installing troggle

    -

    The :troggle: repo is the python source code for troggle. This is what you will be editing. There are over 8,000 lines of python code (excluding comments and blank lines) and over 2,000 lines of HTML/django template code. This is over 600 files in over 400 folders, but only 38MB in size. +

    The :troggle: repo is the python source code for troggle. This is what you will be editing. There are over 8,000 lines of python code (excluding comments and blank lines) and over 2,000 lines of HTML/Django template code. This is over 600 files in over 400 folders, but only 38MB in size.

    key exchange

    Follow this link to register a key with the expo server to get git access if you have not already cloned the :troggle: repo. @@ -204,6 +204,12 @@ Nearly half the code deals with importing and parsing data, so you need to test

    Use git to commit your edits

    You need to know git. Sorry, but there it is. See our git repositories and our git cheat sheet. +

    Helpful database tools and scripts

    + + +

    The public server uses a MariaDB SQL database and development is usually done using a single-user sqlite database which is a standard Django option. +

    +You will find it very, very useful to see what is going on if you look directly at the data in the database (just a single file in the sqlite case) and browse the data in the tables. This is vital when doing Django migrations between Django versions. A light-weight, simple db browser is DB Browser for SQLite. Connecting directly the the MariaDB database with a control panel or workbench gives even more tools and documentation capabilities.

    diff --git a/handbook/troggle/trognotes.html b/handbook/troggle/trognotes.html index a7d517565..c6e9f9a49 100644 --- a/handbook/troggle/trognotes.html +++ b/handbook/troggle/trognotes.html @@ -27,7 +27,7 @@ and you will also also have merely skimmed as irrelevant or trivial: -

    Creating your own system development machine

    -

    It's a simple sequence: +

    Creating your own system development machine

    +

    It's a simple sequence whcih steadily builds your expertise:

    1. Use the online forms and reports. +
    2. Read documentation to get the concepts and structures into your head, so that you can see how it all fits together and works.
    3. Explore the public pages of the 4 git repositories including all the source code
    4. Use the online forms and reports together with 'survex' and 'therion' installed on your own laptop.
    5. Get the 'expoadmin' password and explore the live system online: watch the data change in real time