mirror of
https://expo.survex.com/repositories/expoweb/.git/
synced 2025-01-30 07:02:44 +00:00
django documentaiton updates
This commit is contained in:
Philip Sargent
parent
fa81616797
commit
ecaaec7927
@ -136,6 +136,7 @@ Things that are likely to be relevant at basecamp.
|
||||
<li><a href="survey/index.htm">Surveying guide</a></li>
|
||||
<li><a href="look4.htm">Prospecting guide</a></li>
|
||||
<li><a href="rescue.htm">Rescue guide</a></li>
|
||||
<li><a href="computing/onlinesystems.html">Online systems</a></li>
|
||||
</ul></li>
|
||||
<li><a href="../infodx.htm">Main index</a></li>
|
||||
<li><a href="../index.htm">Expo Home</a></li>
|
||||
|
||||
@ -41,7 +41,7 @@ This is where we decide which aspects of the real world <em>we will ignore</em>
|
||||
|
||||
<p>We only need <strong>implementation-level</strong> diagrams for tiny, tricky issues. Python is very clear so serves as its own implementation specification. However Django does need some explanation even to a competent python programmer if they have not used it before.
|
||||
|
||||
<p>For a fundamental background to system specification the classic work of <a href="http://www.syntropy.co.uk/syntropy/designing-object-systems.pdf">Cook and Daniels</a> (online PDF, 400 pages) cannot easily be improved upon (start reading at page 10, second paragraph).
|
||||
<p>For a fundamental background to system specification the classic work of <a href="/expofiles/documents/designing-object-systems.pdf">Cook and Daniels</a> (online PDF, 400 pages) cannot easily be improved upon (start reading at page 10, second paragraph).
|
||||
|
||||
|
||||
<h3>Class Diagrams</h3>
|
||||
@ -103,7 +103,7 @@ You can edit your own version to revise this when it becomes outdated. <br>This
|
||||
|
||||
</code></pre>
|
||||
<h3 id="cookanddaniels">Cook & Daniels - Three Levels</h3>
|
||||
<p>From <a href="http://www.syntropy.co.uk/syntropy/designing-object-systems.pdf">Cook and Daniels</a> (online PDF, 400 pages, pp10-11):
|
||||
<p>From <a href="/expofiles/documents/designing-object-systems.pdf">Cook and Daniels</a> (online PDF, 400 pages, pp10-11):
|
||||
<div style="text-align: left; font-size: smaller; margin-left: 7%; margin-right:15%">
|
||||
<p>
|
||||
"In this book we present three kinds of object-oriented model. The first kind, which
|
||||
|
||||
@ -10,9 +10,19 @@
|
||||
<h1>Troggle Architecture</h1>
|
||||
<style>figure {font-weight: bold; font-size: small; font-family: sans-serif;font-variant-caps: small-caps;}</style>
|
||||
|
||||
<h2>Troggle overall architecture</h2>
|
||||
<p>Troggle is made up of three large chunks:
|
||||
<ul>
|
||||
<li>The <strong>website pages</strong>: the handbook, instructions, indexes, reference material, walking guides,
|
||||
logbook typescripts, reports to funding agencies, copies of expo reports in magazines, instruction guides for how to run an expo, accounting protocols for subsidising transport, rope maintenance standards: over 900 pages in all. What you are reading now is part of this.<br><br>
|
||||
<li>The <strong>file archive</strong>: the photo galleries, the copies of PDF reports, the scans of original survey notebooks, GPS tracks, maps, aerial photos, scanned images of our handwritten expo logbooks. There are 40 GB of files.<br><br>
|
||||
<li>The <strong>troggle-generated reports</strong>: the tables of survey trips for each cave, the lists of scanned surveys for each survey trip, who was on what trip, calendar lists of logbook entries corrleated with recorded survey trips, who surveyed what caves, what source material was used to create the final cave survey images, who went on which expeditions (and who didn't go caving). There are over 2,000 webpages generated using over 6,000 lines of bespoke python code from over 90 different urls.
|
||||
</ul>
|
||||
|
||||
|
||||
<h3>Troggle data architecture</h3>
|
||||
<p>
|
||||
The core of troggle is the data architecture: the set of tables into which all the cave survey and expo data is poured and stored. These tables are what enables us to produce a large number of different but consistent reports and views.
|
||||
The core of the troggle software is the data architecture: the set of tables into which all the cave survey and expo data is poured and stored. These tables are what enables us to produce a large number of different but consistent reports and views.
|
||||
<div style="display: flex">
|
||||
<div style="flex: 50%">
|
||||
<figure>
|
||||
@ -29,7 +39,7 @@ The core of troggle is the data architecture: the set of tables into which all t
|
||||
</figure>
|
||||
</div></div>
|
||||
<p>
|
||||
ALSO there have been tables added to the core representation which are not anticipated in that document of this diagram, e.g. Scannedimage, Survexdirectory, Survexscansfolder, Survexscansingle, Tunnelfile, TunnelfileSurvexscansfolders, Survey. See <a href="datamodel.html">Troggle data model</a> python code (15 May 2020) and click on the Class Diagram below on the right.
|
||||
Also there have been tables added to the core representation which are not included in this old diagram, e.g. Scannedimage, Survexdirectory, Survexscansfolder, Survexscansingle, Tunnelfile, TunnelfileSurvexscansfolders, Survey. See <a href="datamodel.html">Troggle data model</a> python code (15 May 2020) and click on the Class Diagram below on the right.
|
||||
<div class="onright">
|
||||
<figure>
|
||||
<a href="../l/trogclass-1.html"><img src="../t/trogclass-1.jpg"></a>
|
||||
|
||||
@ -8,10 +8,24 @@
|
||||
<body><style>body { background: #fff url(/images/style/bg-system.png) repeat-x 0 0 }</style>
|
||||
<h2 id="tophead">CUCC Expedition Handbook</h2>
|
||||
<h1>Django and Troggle</h1>
|
||||
|
||||
<h3>Django Versions and troggle</h3>
|
||||
<p>Troggle is built on top of the django framework. In 2019 we had let ourselves get rather behind in keeping up to date with the current django version and this held us back from upgrading the operating system - which we needed to do. Troggle uses several community-contributed django plugins and each of these had their own version dependencies. We also got caught up with out of date and deprecated python language features.
|
||||
<p>A ridiculous amount of work was required to get to a situation where troggle was running on relatively recent and nearly security-in-date versions of python, django, plugins and linux by Summer 2020. We don't want that to happen again.
|
||||
<h3>Three sentence intro to Django for python programmers</h3>
|
||||
<ul>
|
||||
<li>There are many 'magic' function calls autogenerated. So when we create a <var>'Cave'</var> class (subclass of Django <var>Model</var>), with an instance <var>'caveenetrance'</var> we automagically define functions such as:
|
||||
<ul>
|
||||
<li><var>Cave.objects.filter()</var>
|
||||
<li><var>Cave.objects.all()</var>
|
||||
<li><var>Cave.caveandentrance_set.all</var>
|
||||
</ul>
|
||||
note that the suffix on a name '<var>'_set</var> actually denotes a function call to the database. Don't let this upset you.
|
||||
|
||||
<li>You will get very familiar with the <a href="https://docs.djangoproject.com/en/2.2/">online documentation</a>. be sure to be looking that the flavour for the right release of Django (indicated on the bottom-right of the screen: the link here goes to v2.2). You can read it in Polish, Indonesian, Brazilian-Portuguese or whatever if you prefer.
|
||||
|
||||
<li>Django has a good process for migrating both the python code and the SQL database to later versions of Django via <a href="https://docs.djangoproject.com/en/2.2/topics/migrations/">'migrations'</a>. Note that even though Expo imports all the data from files and its database is ephemeral (but it is intensely used for cross-referencing), the database schema still needs to be migrated.
|
||||
</ul>
|
||||
<h4>Django versions and deprecation</h4>
|
||||
<a href="https://www.djangoproject.com/download#supported-versions">
|
||||
<img border="1" class="onright" width="250px" src='release-roadmap.3c7ece4f31b3.png'/></a></a>
|
||||
@ -19,6 +33,7 @@
|
||||
<li>Django has a mature and reliable release programme: <a href="https://docs.djangoproject.com/en/dev/releases/">docs.djangoproject.com<wbr>/en/<wbr>dev/<wbr>releases/</a>
|
||||
<li>Django pre-announces which features will be deprecated: <a href="https://docs.djangoproject.com/en/dev/internals/deprecation/">docs.djangoproject.com<wbr>/en/<wbr>dev/<wbr>internals/<wbr>deprecation/</a>
|
||||
<li>Django release schedule: <a href="https://www.djangoproject.com/download/">supported versions timetable</a>
|
||||
<li>Significant new Django versions are released every 8 months. Deprecated features after removed after the two subsequent versions.
|
||||
</ul>
|
||||
|
||||
<h4>Django plugins</h4>
|
||||
@ -30,12 +45,12 @@
|
||||
<p>Well we <a href="trog2030.html">might not use django indefinitely</a>, but unlike many frameworks the necessary functions are separately replaceable. So this gives us an evolution path. We can incrementally reduce the amount of django we use, replacing it with our own simpler python that does only what we need.
|
||||
<p>The separate functions within the framework form a "stack". These functions exist in all web application frameworks but in Django they are <a href="https://docs.djangoproject.com/en/dev/misc/design-philosophies/">loosely coupled</a>.
|
||||
<p>The stack is:
|
||||
<ul>
|
||||
<li>database: <a href="https://docs.djangoproject.com/en/dev/topics/db/">mapping</a> to/from python objects and indexing/access routines for all the entries,
|
||||
<ol>
|
||||
<li>SQL database: <a href="https://docs.djangoproject.com/en/dev/topics/db/">mapping</a> to/from python objects and indexing/access routines for all the entries (sqlite, MySQL, MariaDB, postgres all work)
|
||||
<li>request/response (<a href="https://docs.djangoproject.com/en/dev/ref/request-response/">http GET/POST</a>) including <a href="https://docs.djangoproject.com/en/dev/topics/auth/default/#auth-web-requests">access control</a> and <a href="https://www.moesif.com/blog/engineering/middleware/What-Is-HTTP-Middleware/">security middleware</a>,
|
||||
<li><a href="https://docs.djangoproject.com/en/dev/topics/http/urls/">URL mapping/dispatch</a> which matches a requested URL with a chunk of python code, and vice versa (declarative and bidrectional),
|
||||
<li><a href="https://docs.djangoproject.com/en/dev/topics/templates/">templates</a> which format the results of data queries into HTML pages or JSON data exports
|
||||
</ul>
|
||||
</ol>
|
||||
|
||||
<p>See the <a href="https://docs.djangoproject.com/en/dev/misc/design-philosophies/">django design philosophy</a>. Note that having a URL dispatcher that supports <a href="https://docs.djangoproject.com/en/dev/topics/http/urls/#s-reverse-resolution-of-urls">reverse resolution</a> is important: it is a key reason why we need a framework and not just a mess of javascript. We have nearly 100 URL patterns.
|
||||
|
||||
|
||||
@ -22,17 +22,18 @@ fix import errors by re-editing the input files: survex, tunnel, or logbook.
|
||||
<a href="/personexpedition/MartinGreen/2002">per-person caving</a> - list of logbook trips and surveys for one person<br>
|
||||
<a href="/people">people</a> - who caved when and how much did they survey<br>
|
||||
<a href="/logbookentry/2018-07-19/balkon-to-honeycomb-hangmans">logbook entry</a> - who, where and what<br>
|
||||
<a href="/survey_scans">survey_scans</a> - all wallets of scanned surveys and corresponding survex files<br>
|
||||
<a href="/survey_scans/">survey_scans</a> - all wallets of scanned surveys and corresponding survex files<br>
|
||||
<a href="/survey_scans/2014%252347/">per-wallet links</a> - links to scan files and survex files from one wallet<br>
|
||||
<a href="/tunneldata">tunneldata</a> - all the tunnel drawings and the wallets and scanned images they derive from<br>
|
||||
<a href="/tunneldata/">tunneldata</a> - all the tunnel drawings and the wallets and scanned images they derive from<br>
|
||||
<br>
|
||||
<a href="/admin/core/dataissue/l">/admin/core/dataissue/</a> - where the data import errors and warnings are recorded<br>
|
||||
<br>
|
||||
Configuration aids when setting up on a new machine (move to main manual):<br>
|
||||
<a href="/pathsreport">pathsreport</a> - debugging aid<br>
|
||||
<em>How to set up troggle on a new machine. <br>
|
||||
Copies of the older material where that is illuminating.<br>
|
||||
...needs more work...</em>
|
||||
|
||||
|
||||
|
||||
|
||||
<hr />
|
||||
|
||||
Return to: <a href="trogintro.html">Troggle intro</a><br />
|
||||
|
||||
@ -14,7 +14,6 @@
|
||||
<a href="trogintro.html">Troggle - Introduction</a> - what it is<br>
|
||||
<a href="trogusers.html">Troggle - the Users</a> - Who needs to know What and When<br>
|
||||
<a href="trogdocm.html">Troggle - Fixing things</a> - users' manuals for data import<br>
|
||||
<a href="trogimport.html">Troggle - Data Import</a> - reset and import data<br>
|
||||
<a href="trogmanual.html">Troggle - Maintenance</a> - list of maintenance tasks<br>
|
||||
<a href="trogarch.html">Troggle - Architecture</a> - diagrams, files, structure<br>
|
||||
<a href="datamodel.html">Troggle - Data Model</a> - syntax-coloured list of classes, instance variables and foreign keys<br>
|
||||
@ -27,6 +26,7 @@
|
||||
<li><a href="trog2030.html">Troggle in 2025-2030</a> - architectural evolution proposal<br>
|
||||
</ul>
|
||||
<a href="serverconfig.html">Troggle server configuration</a> - how to get troggle running on a new machine (incoimplete!)<br>
|
||||
<a href="trogimport.html">Troggle - Data Import</a> - reset and import data<br>
|
||||
<a href="trogdjango.html">Troggle and Django</a> - The Django web framework we use<br>
|
||||
<a href="trogdjangup.html">Troggle: updating Django</a> - Upgrading troggle to use a later Django version<br>
|
||||
<a href="unittests.html">Troggle unit tests</a> - test suite for programmers<br>
|
||||
|
||||
@ -44,7 +44,7 @@ The troggle software is written and maintained by expo members.
|
||||
<li>Coherently publishes expo data by cave, by expedition, by person, by trip or by survey - without requiring duplicate data entry.
|
||||
|
||||
<li>Manages and safely archives the typed and scanned survey data, entrance data, trip records (logbooks) and expo records.
|
||||
<li>Enforces consistency - making it easier to detect mistakes and omissions
|
||||
<li>Encourages consistency - making it easier to detect inconsistencies and omissions, and making mistakes visible
|
||||
<li>Publishes the "guidebook descriptions" of caves by a combination of online forms and uploading files.
|
||||
<li>Supports the process of turning scribbled notes into finished cave surveys
|
||||
<li>Generates prospecting guides so that we don't waste time looking at holes which have already been explored
|
||||
|
||||
Loading…
Reference in New Issue
Block a user