Merge pull request SensorsIot#535 from Paraphraser/20220327-python-doco-master

20220327 Python documentation

Author: Slyke

docs/Containers/Python.md

@@ -1,12 +1,12 @@
 # Python
 
-## references
+## <a name="references"></a>references
 
 * [Python.org](https://www.python.org)
 * [Dockerhub image library](https://hub.docker.com/_/python)
 * [GitHub docker-library/python](https://github.com/docker-library/python)
 
-## selecting Python in the IOTstack menu
+## <a name="menuPython"></a>selecting Python in the IOTstack menu
 
 When you select Python in the menu:
 
@@ -42,7 +42,7 @@ When you select Python in the menu:
 	  - ./volumes/python/app:/usr/src/app
 	```
 
-### customising your Python service definition
+### <a name="customisingPython"></a>customising your Python service definition
 
 The service definition contains a number of customisation points:
 
@@ -70,7 +70,7 @@ $ cd ~/IOTstack
 $ docker-compose up -d python
 ```
 
-## Python - first launch
+## <a name="firstLaunchPython"></a>Python - first launch
 
 After running the menu, you are told to run the commands:
 
@@ -139,7 +139,7 @@ This is what happens:
 
 	Pressing <kbd>control</kbd>+<kbd>c</kbd> terminates the log display but does not terminate the running container.
 
-## stopping the Python service
+## <a name="stopPython"></a>stopping the Python service
 
 To stop the container from running, either:
 
@@ -157,7 +157,7 @@ To stop the container from running, either:
 	$ docker-compose rm --force --stop -v python
 	```
 
-## starting the Python service
+## <a name="startPython"></a>starting the Python service
 
 To bring up the container again after you have stopped it, either:
 
@@ -175,23 +175,23 @@ To bring up the container again after you have stopped it, either:
 	$ docker-compose up -d python
 	```
 
-## Python - second-and-subsequent launch
+## <a name="reLaunchPython"></a>Python - second-and-subsequent launch
 
 Each time you launch the Python container *after* the first launch:
 
 1. The existing local image (`iotstack_python`) is instantiated to become the running container.
 2. The `docker-entrypoint.sh` script runs and performs "self-repair" by replacing any files that have gone missing from the persistent storage area. Self-repair does **not** overwrite existing files! 
 3. The `app.py` Python script is run.
 
-## when things go wrong - check the log
+## <a name="debugging"></a>when things go wrong - check the log
 
 If the container misbehaves, the log is your friend:
 
 ``` console
 $ docker logs python
 ```
 
-## project development life-cycle
+## <a name="yourPythonScript"></a>project development life-cycle
 
 It is **critical** that you understand that **all** of your project development should occur within the folder:
 
@@ -201,7 +201,7 @@ It is **critical** that you understand that **all** of your project development
 
 So long as you are performing some sort of routine backup (either with a supplied script or a third party solution like [Paraphraser/IOTstackBackup](https://github.com/Paraphraser/IOTstackBackup)), your work will be protected.
 
-### getting started
+### <a name="gettingStarted"></a>getting started
 
 Start by editing the file:
 
@@ -222,7 +222,7 @@ $ cd ~/IOTstack
 $ docker-compose restart python
 ```
 
-### reading and writing to disk
+### <a name="persistentStorage"></a>reading and writing to disk
 
 Consider this line in the service definition:
 
@@ -249,7 +249,7 @@ What it means is that:
 
 If your script writes into any other directory inside the container, the data will be lost when the container re-launches.
 
-### getting a clean slate
+### <a name="cleanSlate"></a>getting a clean slate
 
 If you make a mess of things and need to start from a clean slate, erase the persistent storage area:
 
@@ -262,7 +262,7 @@ $ docker-compose up -d python
 
 The container will re-initialise the persistent storage area from its defaults.
 
-### adding packages
+### <a name="addingPackages"></a>adding packages
 
 As you develop your project, you may find that you need to add supporting packages. For this example, we will assume you want to add "[Flask](https://pypi.org/project/Flask/)" and "[beautifulsoup4](https://pypi.org/project/beautifulsoup4/)".
 
@@ -316,7 +316,7 @@ To make *Flask* and *beautifulsoup4* a permanent part of your container:
 	Flask==2.0.1
 	```
 
-5. Continue your development work by returning to [getting started](#getting-started).
+5. Continue your development work by returning to [getting started](#gettingStarted).
 
 Note:
 
@@ -340,11 +340,11 @@ Note:
 
 	The `requirements.txt` file will be recreated and it will be a copy of the version in the *services* directory as of the last image rebuild.
 
-### making your own Python script the default
+### <a name="scriptBaking"></a>making your own Python script the default
 
-Suppose the Python script you have been developing reaches a major milestone and you decide to "freeze dry" your work up to that point so that it becomes the default when you ask for a [clean slate](#getting-a-clean-slate). Proceed like this:
+Suppose the Python script you have been developing reaches a major milestone and you decide to "freeze dry" your work up to that point so that it becomes the default when you ask for a [clean slate](#cleanSlate). Proceed like this:
 
-1. If you have added any packages by following the steps in [adding packages](#adding-packages), run the following command:
+1. If you have added any packages by following the steps in [adding packages](#addingPackages), run the following command:
 
 	``` console
 	$ docker exec python bash -c 'pip3 freeze >requirements.txt'
@@ -406,11 +406,11 @@ Suppose the Python script you have been developing reaches a major milestone and
 	$ docker system prune -f
 	```
 
-### canning your project
+### <a name="scriptCanning"></a>canning your project
 
 Suppose your project has reached the stage where you wish to put it into production as a service under its own name. Make two further assumptions:
 
-1. You have gone through the steps in [making your own Python script the default](#making-your-own-python-script-the-default) and you are **certain** that the content of `./services/python/app` correctly captures your project.
+1. You have gone through the steps in [making your own Python script the default](#scriptBaking) and you are **certain** that the content of `./services/python/app` correctly captures your project.
 2. You want to give your project the name "wishbone".
 
 Proceed like this:
@@ -471,7 +471,7 @@ Remember:
 	~/IOTstack/volumes/wishbone/app
 	``` 
 
-## routine maintenance
+## <a name="routineMaintenance"></a>routine maintenance 
 
 To make sure you are running from the most-recent **base** image of Python from Dockerhub:
 
@@ -495,4 +495,4 @@ The old base image can't be removed until the old local image has been removed,
 
 Note:
 
-* If you have followed the steps in [canning your project](#canning-your-project) and your service has a name other than `python`, just substitute the new name where you see `python` in the two `dockerc-compose` commands.
+* If you have followed the steps in [canning your project](#scriptCanning) and your service has a name other than `python`, just substitute the new name where you see `python` in the two `dockerc-compose` commands.