Merge pull request #11 from MrClock8163/feature/docs

Documentation update

Author: MrClock8163

README.md

@@ -1,4 +1,6 @@
-# I-man
+<h1 align="center">
+<img src="https://raw.githubusercontent.com/mrclock8163/instrumentman/main/docs/iman_logo.png" alt="I-man logo" width="300">
+</h1><br>
 
 [![PyPI - Version](https://img.shields.io/pypi/v/instrumentman)](https://pypi.org/project/instrumentman/)
 [![Python Version](https://img.shields.io/python/required-version-toml?tomlFilePath=https%3A%2F%2Fraw.githubusercontent.com%2FMrClock8163%2FInstrumentman%2Frefs%2Fheads%2Fmain%2Fpyproject.toml)](https://pypi.org/project/instrumentman/)

docs/_static/css/custom.css

@@ -1,12 +1,12 @@
 
 :root > * {
-    --md-primary-fg-color: #90AF90;
+    --md-primary-fg-color: #CFB41A;
     --md-accent-fg-color: #a9221d;
-    --md-typeset-a-color: #4a644c;
+    /* --md-typeset-a-color: #4a644c; */
 }
 
 [data-md-color-scheme="slate"] {
     /* --md-primary-fg-color:#4a644c; */
-    --md-typeset-a-color: #90AF90;
+    --md-typeset-a-color: #CFB41A;
     --md-code-bg-color: #333746;
 }

docs/_static/favicon.svg

@@ -0,0 +1,30 @@
+Information
+===========
+
+Command Structure
+-----------------
+
+Different applications might implement multiple different commands, that are
+relevant to the task. While these are defined and documented in application
+subpackages, on the user level, the commands are grouped into action based
+command groups instead for easier use.
+
+For instance, the Set Measurement application defines commands for conducting
+the measurements themselves, validating and merging multiple session outputs,
+and also for calculating results. These can be accessed through the following
+commands:
+
+.. code-block:: shell
+
+    iman measure sets -h
+    iman merge sets -h
+    iman validate sets -h
+    iman calc sets -h
+
+Documentation
+-------------
+
+The different commands are documented in their application groups to give
+a better overview of the processes. Every page shows the actual command to
+invoke the program, some additional context and optional examples, and an
+automatically generated view of the ``--help`` page of the command.

docs/_static/logo.svg

@@ -0,0 +1 @@
+.. mdinclude:: ../CHANGELOG.md

docs/about.rst

@@ -0,0 +1,54 @@
+Downloading
+===========
+
+A useful file management feature is the ability to download a file from the
+instrument. The download command can be used to download a file identified
+by either a file name and type, or a full file path.
+
+.. caution::
+    :class: warning
+
+    File downloads over serial (especially Bluetooth) are rather slow, and
+    greatly affected by the communication speed settings.
+
+Process
+-------
+
+The download process is carried out by exchanging chunks of data. The
+individual chunks are sent down by the instrument, and slowly reassambled on
+the receiving side. The block size can be customized, but the maximum is 450
+hex characters/block (or 225 bytes). Newer instruments support large file
+downloads, where the block size can be increased up to 1800 characters/block.
+
+Under normal circumstances it is recommended to use the maximum chunk size,
+as this results in the fastest transfer. If the connection is not completely
+reliable, decreasing the chunk size might reduce the size of data, that needs
+to be resent due to timed out exchanges.
+
+Requirements
+------------
+
+- GeoCom capable instrument
+
+Examples
+--------
+
+.. code-block:: shell
+    :caption: Downloading the root file of a job
+
+    iman download file -f database COM1 job.xcf job.xcf
+
+    // or
+    
+    iman download file COM1 DBX/job.xcf job.xcf
+
+.. code-block:: shell
+    :caption: Downloading an exported file from a CF card
+
+    iman list files -d cf COM1 Data/coordinates.txt coordinates.txt
+
+Usage
+-----
+
+.. click:: instrumentman.filetransfer:cli_download
+    :prog: iman download file

docs/changelog.rst

@@ -0,0 +1,13 @@
+:icon: material/file-outline
+
+Files
+=====
+
+Newer instruments implement file system commands, that can be used to
+manage, browse or retrieve files from the device.
+
+.. toctree::
+    :maxdepth: 1
+
+    list
+    download

docs/commands/files/download.rst

@@ -0,0 +1,44 @@
+Listing
+=======
+
+The most basic file management function is the ability to list files of
+a specified type in a specified directory on a memory device of the instrument.
+
+The listing command can be used to retrieve the list of files belonging to a
+certain file type, or located in a certain directory. In addition to the
+file name, the file size in bytes and the date of last modification is also
+displayed.
+
+Requirements
+------------
+
+- GeoCom capable instrument
+
+Paths
+-----
+
+The most general way of file listing is to not specify a file type (defaulting
+to unknown), and giving the directory path. Such a path should use ``/`` as
+separators (contrary to other Windows conventions) and should end with a ``/``.
+
+If a special type of file is to be listed (e.g. database), then it is enough
+to specify the file type, the path can be left out.
+
+Examples
+--------
+
+.. code-block:: shell
+    :caption: Listing database files in internal memory
+
+    iman list files -f database COM1
+
+.. code-block:: shell
+    :caption: Listing all exported files on a CF card
+
+    iman list files -d cf COM1 Data/
+
+Usage
+-----
+
+.. click:: instrumentman.filetransfer:cli_list
+    :prog: iman list files

docs/commands/files/index.rst

@@ -0,0 +1,33 @@
+Calculation
+===========
+
+After the measurements are done, the average inclination and the deviation
+can be calculated from the results. The results give the coordinate system
+axis-aligned inclination components and standard deviations, as well as the
+resulting inclination and its direction.
+
+Methodology
+-----------
+
+In each horizontal position 2 angles are given. The calculation is carried
+out with the following general steps:
+
+#. For each position
+
+   #. Calculate cross and length offset of the standing axis 1 meter above
+      the measurement center.
+   #. Convert cross-length coordinates to polar
+   #. Correct inclination direction with instrument bearing
+   #. Convert polar inclination back to coordinates
+
+#. Calculate mean and deviation of inclination coordinates
+#. Convert mean coordinates to angles for axis-aligned results
+#. Convert mean coordinates to polar inclination
+
+Results can be either printed to the terminal, or saved a CSV file.
+
+Usage
+-----
+
+.. click:: instrumentman.inclination:cli_calc
+    :prog: iman calc inclination