Merge pull request #73 from babeloff/main

A big bunch of changes
FreeTAKTeam · May 9, 2024 · 9367a94 · 9367a94
2 parents 75c2df5 + 8c4b985
commit 9367a94
Show file tree

Hide file tree

Showing 187 changed files with 1,726 additions and 1,025 deletions.
diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml
@@ -13,20 +13,28 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
-      - uses: actions/setup-python@v4
+      - name: Configure Git Credentials
+        run: |
+          git config user.name github-actions[bot]
+          git config user.email 41898282+github-actions[bot]@users.noreply.github.com
+      - uses: actions/setup-python@v5
         with:
           python-version: 3.x
-#      - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV
-#      - uses: actions/cache@v3
-#        # https://github.com/actions/cache
-#        with:
-#          key: mkdocs-material-${{ env.cache_id }}
-#          path: .cache
-#          restore-keys: |
-#            mkdocs-material-
+      - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV
+      - uses: actions/cache@v4
+        # https://github.com/actions/cache
+        with:
+          key: mkdocs-material-${{ env.cache_id }}
+          path: .cache
+          restore-keys: |
+            mkdocs-material-
       - run: >-
           pip install mkdocs-material mkdocs-awesome-pages-plugin 
           mkdocs-section-index mkdocs-toc-sidebar-plugin mike 
           markdown-include mkdocs-pdf-export-plugin
+          mkdocs-mermaid2-plugin
+          httplib2
+          mkdocs_build_plantuml_plugin
+          mkdocs-exclude mkdocs-minify-plugin mkdocs-versioning
       # https://www.mkdocs.org/user-guide/cli/#mkdocs-gh-deploy
-      - run: cd docs && mkdocs gh-deploy --force
+      - run: mkdocs gh-deploy --force
diff --git a/README.md b/README.md
@@ -55,3 +55,24 @@ For example, here is an excerpt from the LICENSE file.
 {!LICENSE!lines=1  3 8-10  2}
 ```
 
+
+### `attr_list`
+The documentation uses the `attr_list` extension which
+adds a syntax to define attributes on the various HTML elements in markdown’s output. 
+The official documentation for `attr_list` is located in the [project repo](https://python-markdown.github.io/extensions/attr_list/).
+
+Some uses:
+
+* resizing images
+* associating classes with elements
+
+
+### `mkdocs-mermaid2-plugin`
+The documentation uses Mermaid2 to make network-deployment-diagrams.
+
+### `mkdocs_build_plantuml`
+The documentation uses PlantUML to make network-deployment-diagrams.
+https://github.com/quantorconsulting/mkdocs_build_plantuml
+This tooling supports more of C4 and UML.
+
+
diff --git a/docs/.pages b/docs/.pages
@@ -0,0 +1,9 @@
+nav:
+    - Overview: index.md
+    - About: About
+    - Try Me: Usage
+    - Installation: Installation
+    - Troubleshooting: Troubleshooting
+    - Administration: administration
+    - How to Help: HowToHelp
+    - API: API
diff --git a/docs/docs/API/.pages → docs/API/.pages b/docs/docs/API/.pages → docs/API/.pages
diff --git a/docs/docs/API/REST_API_Doc.md → docs/API/REST_API_Doc.md b/docs/docs/API/REST_API_Doc.md → docs/API/REST_API_Doc.md
@@ -1,6 +1,3 @@
----
-status: ood
----
 
 # REST API - Public
 

diff --git a/docs/docs/API/REST_API_InternalDoc.md → docs/API/REST_API_InternalDoc.md b/docs/docs/API/REST_API_InternalDoc.md → docs/API/REST_API_InternalDoc.md
@@ -1,6 +1,3 @@
----
-status: ood
----
 
 # REST API - Internal
 Internal APIs are primarily used by the FTS UI to communicate with the server. 

diff --git a/docs/docs/About/.pages → docs/About/.pages b/docs/docs/About/.pages → docs/About/.pages
@@ -2,5 +2,6 @@ nav:
     - Frequently Asked Questions: FAQ.md
     - Feature Comparison: FeaturesCompared.md
     - Free TAK Manifesto: Manifesto.md
+    - Why a Free TAK Server: why_fts.md
     - Public Server: PubServer.md
     - Architecture: architecture
diff --git a/docs/docs/About/FAQ.md → docs/About/FAQ.md b/docs/docs/About/FAQ.md → docs/About/FAQ.md
@@ -1,6 +1,3 @@
----
-status: ood
----
 
 # Frequently Asked Questions (FAQ) about FreeTAKServer (FTS)
 
@@ -19,7 +16,7 @@ and integration with other non-TAK systems (e.g., video, audio, Telegram) using
 ## There are other servers for TAK. Why should I use FTS?
 FTS is not only powerful–it's also more user-friendly when [compared](FeaturesCompared.md) to other systems.
 Also, FTS is a community-driven Open Source project at its core.
-Under the covers, FTS is based on a [domain model](architecture/CoTDomain.md),
+Under the covers, FTS is based on a [domain model](architecture/cot_domain.md),
 so it is the only TAK server that can provide analysis and interpretation
 of the information it collects–not just receive requests from clients
 and provides the requested data or perform the requested actions.

diff --git a/docs/docs/About/FeaturesCompared.md → docs/About/FeaturesCompared.md b/docs/docs/About/FeaturesCompared.md → docs/About/FeaturesCompared.md
@@ -1,15 +1,13 @@
----
-status: ood
----
 
 # FreeTAKServer Compared
-Users have spoken: FTS is the best TAK server on github!
 
-## Star History
+Users have spoken: FTS is the best TAK server on GitHub!
 
-[![Star History Chart](https://api.star-history.com/svg?repos=FreeTAKTeam/FreeTakServer,TAK-Product-Center/Server,tkuester/taky&type=Date)](https://star-history.com/#FreeTAKTeam/FreeTakServer&TAK-Product-Center/Server&tkuester/taky&Date)
+## GitHub Star History
 
+[![Star History Chart](https://api.star-history.com/svg?repos=FreeTAKTeam/FreeTakServer,TAK-Product-Center/Server,tkuester/taky&type=Date)](https://star-history.com/#FreeTAKTeam/FreeTakServer&TAK-Product-Center/Server&tkuester/taky&Date)
 
+## Functional Comparison
 
 *Legend*
 
@@ -21,7 +19,6 @@ Users have spoken: FTS is the best TAK server on github!
 1. Full: 100% implementation of the specs 
 2. Extended: > 100% the functions exceed the original Specification
 
-## Function
 |         Function          |          FTS 1.9          |   TAKServer   |           FTS 2.X           |     Other     |
 |:-------------------------:|:-------------------------:|:-------------:|:---------------------------:|:-------------:|
 |    Web Administration     |  O (Single Page Web App)  |       O       |  O (Extended Multi Server)  |       X       |

diff --git a/docs/docs/About/Manifesto.md → docs/About/Manifesto.md b/docs/docs/About/Manifesto.md → docs/About/Manifesto.md
@@ -1,6 +1,3 @@
----
-status: ood
----
 
 # Manifesto for FreeTAKTeam
 

diff --git a/docs/docs/About/PubServer.md → docs/About/PubServer.md b/docs/docs/About/PubServer.md → docs/About/PubServer.md
@@ -1,6 +1,3 @@
----
-status: ood
----
 
 ## Connecting to FTS Public Server 
 

diff --git a/docs/docs/About/architecture/.pages → docs/About/architecture/.pages b/docs/docs/About/architecture/.pages → docs/About/architecture/.pages
diff --git a/docs/docs/About/architecture/cot_domain.md → docs/About/architecture/cot_domain.md b/docs/docs/About/architecture/cot_domain.md → docs/About/architecture/cot_domain.md
@@ -1,6 +1,3 @@
----
-status: todo
----
 
 # **CoT Domain Model**
 

diff --git a/.../docs/About/architecture/cot_hierarchy.md → docs/About/architecture/cot_hierarchy.md b/.../docs/About/architecture/cot_hierarchy.md → docs/About/architecture/cot_hierarchy.md
@@ -1,6 +1,3 @@
----
-status: todo
----
 
 # Work in progress CoT Hierarchy Tree
 

diff --git a/docs/docs/About/architecture/cot_table.md → docs/About/architecture/cot_table.md b/docs/docs/About/architecture/cot_table.md → docs/About/architecture/cot_table.md
@@ -1,12 +1,9 @@
----
-status: todo
----
 
 # Center On Target (CoT)
 
-The following table combines Center On Target information found in COTTYpes.XML,
+The following table combines Center On Target information found in COTTypes.XML,
 aligning it to MIL-STD-2525 CIDC code (when possible).
-To find more information read the [MIL-STD-D-D-D-2525 documentation](MilSTD2525.md)
+To find more information read the [MIL-STD-D-D-D-2525 documentation](mil_std_2525.md)
 
 | **COTID**           | **Hierarchy**                                                                                                                                                                        | **Name**                                                                                                                                                         | **nickname**     | **"ID"** | **CIDC**                 | **Category1**                        | **Category2**                       | **Category3**                                  |
 |:--------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:-----------------------------------------------------------------------------------------------------------------------------------------------------------------|:-----------------|:---------|:-------------------------|:-------------------------------------|:------------------------------------|:-----------------------------------------------|

diff --git a/docs/docs/About/architecture/mil_std_2525.md → docs/About/architecture/mil_std_2525.md b/docs/docs/About/architecture/mil_std_2525.md → docs/About/architecture/mil_std_2525.md
@@ -1,8 +1,6 @@
----
-status: todo
----
 
 # About [MIL-STD-2525](https://en.wikipedia.org/wiki/NATO_Joint_Military_Symbology) and CoT
+
 The Center on Target (CoT) is a data exchange format primarily used in military and emergency response applications such as the TAK ecosystem.
 It is designed to facilitate real-time sharing of geospatial information among various systems and users. 
 The CoT protocol enables efficient communication of location, status, and other relevant situational data,
@@ -14,6 +12,7 @@ The CoT system is only partially overlapping with 2525.
 On a list of 3000+ CoT's , 1000 are directly traceable to MIL-STD-2525.
 
 The MIL_STD-2525 has had several versions:
+
 * [MIL-STD-2525D](https://www.jcs.mil/Portals/36/Documents/Doctrine/Other_Pubs/ms_2525d.pdf) 2014
 * [MIL-STD-2525C](https://www.jcs.mil/Portals/36/Documents/Doctrine/Other_Pubs/ms_2525c.pdf) 2008
 * [MIL-STD-2525B](http://www.mapsymbs.com/ms2525b_ch1_full.pdf) 2005
@@ -332,7 +331,7 @@ Test code [here:](https://www.spatialillusions.com/milsymbol/example.html#angula
 
 ## Example CoT
 
-Equipment manufacture	Building is part of Gnd/Structure/Factory
+Equipment Manufacture	Building is part of Gnd/Structure/Factory
 
 | **Atom** | ** ** | **Affiliation** | ** ** | ** Ground ** | ** ** | ** Infrastructure ** | ** **  | ** Equipment **  |	
 |:---------|:------|:----------------|:------|:-------------|:------|:---------------------|:-------|:-----------------|

diff --git a/docs/About/why_fts.md b/docs/About/why_fts.md
@@ -0,0 +1,35 @@
+
+I want to emphasize a key principle:
+"Before you ask, ask yourself what you can give."
+Now, you might wonder, why should you give?
+As the authors of FTS, here are our top 10 reasons for creating this software for you:
+
+## WHY FTS IS BETTER
+
+1. Since 2020, FreeTAKServer (FTS) has been a labor of love,
+supported by dozens of volunteers dedicating their free time, including Sundays.
+2. FTS boasts a modern, scalable architecture, completely revamped for the 2.X series.
+3. It's nurtured by a dedicated community that stands up to giants.
+4. Extensive documentation supports users at every step.
+5. FTS is incredibly versatile, capable of running on a wide range of platforms (and no, this don't mean that ANYBOBY can run FTS on everything!) .
+6. It intelligently "understands" COT messages, paving the way for innovative developments.
+7. Our public roadmap invites community involvement and contribution towards a shared vision.
+8. FTS embodies true open-source principles, welcoming everyone to contribute and benefit. we are not hiding behind secrecy and limited access
+9. Installation is straightforward compared to the convoluted process for TAK Server.
+10. We believe in the power of community and open-source development. FTS is not just "our software"; it's a collaborative effort that benefits all users.
+
+## WHY WE DO NOT LIKE TAK Server
+
+1. TAK Server OG is based on ancient (20+ years) J2EE architecture with a lot of spaghetti code.
+2. It's notoriously difficult to install—historically requiring specialized personnel funded by the USG.
+3. The user interface is far from user-friendly.
+4. It's maintained by a mega-corporation charging exorbitant fees for minimal service.
+5. The documentation is either sparse or non-existent.
+6. It demands significant machine resources to operate.
+7. It acts merely as a "broker" without any understanding of the messages it handles.
+8. There's no public roadmap.
+9. Though recently open-sourced, TAK Server lacks a true open-source spirit, focusing mainly on military applications without community engagement.
+10. Pressure from our project contributed to making TAK server publicly available, highlighting its previous exclusivity.
+
+Join us in supporting and contributing to FTS, and let's continue to make it even better together. You can start by giving FTS a star in GitHub:
+On https://github.com/FreeTAKTeam/FreeTakServer, in the top-right corner of the page, click Star.
diff --git a/docs/docs/HowToHelp/.pages → docs/HowToHelp/.pages b/docs/docs/HowToHelp/.pages → docs/HowToHelp/.pages
diff --git a/docs/docs/HowToHelp/DevSetupMambaPyCharm.md → docs/HowToHelp/DevSetupMambaPyCharm.md b/docs/docs/HowToHelp/DevSetupMambaPyCharm.md → docs/HowToHelp/DevSetupMambaPyCharm.md
@@ -1,6 +1,3 @@
----
-status: ood
----
 
 # Setup a development environment for FTS
 ## introduction

diff --git a/docs/docs/HowToHelp/DevSetupPipVScode.md → docs/HowToHelp/DevSetupPipVScode.md b/docs/docs/HowToHelp/DevSetupPipVScode.md → docs/HowToHelp/DevSetupPipVScode.md
@@ -1,6 +1,3 @@
----
-status: ood
----
 
 # Setup a development environment for FTS
 ## introduction

diff --git a/docs/docs/HowToHelp/FTSConfig.yaml → docs/HowToHelp/FTSConfig.yaml b/docs/docs/HowToHelp/FTSConfig.yaml → docs/HowToHelp/FTSConfig.yaml
diff --git a/.../docs/HowToHelp/GettingStartedAsHelper.md → docs/HowToHelp/GettingStartedAsHelper.md b/.../docs/HowToHelp/GettingStartedAsHelper.md → docs/HowToHelp/GettingStartedAsHelper.md
@@ -1,6 +1,3 @@
----
-status: ood
----
 
 # How to help
 Depending on your skill-set and passion you can participate in the project in different ways.

diff --git a/docs/docs/HowToHelp/WriteDocumentation.md → docs/HowToHelp/WriteDocumentation.md b/docs/docs/HowToHelp/WriteDocumentation.md → docs/HowToHelp/WriteDocumentation.md
@@ -1,6 +1,3 @@
----
-status: ood
----
 
 # Write Documentation
 
@@ -50,7 +47,7 @@ FTS makes use of this capability.
 You should generate the documentation with your changes to make sure nothing was inadvertently broken.
 The following shows you an example of how to set up `gh-pages` for your project repository.
 
-![](images/github-pages.png)
+![](images/github-pages-branch.png)
 
 The important thing here is to select `[GitHub Actions]`.
 
@@ -61,7 +58,7 @@ The important thing here is to select `[GitHub Actions]`.
 The documentation is built via GitHub actions.
 Here is the `.github/workflows/main.yml` action:
 ```yaml
-{!../../.github/workflows/main.yml!}
+{!../.github/workflows/main.yml!}
 ```
 name
 : The name of the workflow
@@ -142,6 +139,21 @@ The `fts_user/docs/versions.json` is used to define the versions.
 
 TODO: Explain how this is to be used.
 
+### Mermaid
+
+For simple diagrams we use `Mermaid`.
+
+https://mermaid.js.org/
+
+
+### PlantUML
+
+There are some cases where `Mermaid` is not sufficient such as making `Network Deployment Diagrams`.
+When that happens we use `PlantUML`.
+
+https://github.com/plantuml-stdlib/C4-PlantUML/blob/master/README.md
+
+
 
 ## Writing Good Markdown
 
@@ -165,3 +177,13 @@ that it works well with tools like `git`.
 (This `git` default is seldom changed.)
 This implies that ideas should be confined to lines of text,
 which is precisely what ventilated code.
+
+### Apply Style Judiciously
+
+It may be that a captured image is too large.
+It may be tempting to resize the image.
+However, if a reader wants to see the detail in the image this will lose that detail.
+Instead, apply a style to the image to make it smaller.
+```text
+  ![](rpi-imager-ssh-settings.png){: style="height:200px;width:150px" }
+```
diff --git a/docs/docs/HowToHelp/fts-dev-env.yml → docs/HowToHelp/fts-dev-env.yml b/docs/docs/HowToHelp/fts-dev-env.yml → docs/HowToHelp/fts-dev-env.yml
diff --git a/docs/docs/HowToHelp/fts-doc-env.yml → docs/HowToHelp/fts-doc-env.yml b/docs/docs/HowToHelp/fts-doc-env.yml → docs/HowToHelp/fts-doc-env.yml
@@ -6,12 +6,13 @@ dependencies:
     - mkdocs
     - mkdocs-material
     - mkdocs-material-extensions
-    # - mkdocs-mermaid2
     - mike
     # - mkdocs-jupyter
     - markdown-include
     - pip
     - pip:
         - mkdocs-awesome-pages-plugin
         - mkdocs-section-index
-        - mkdocs-pdf-export-plugin
+        - mkdocs-pdf-export-plugin
+        - mkdocs-mermaid2-plugin
+        - mkdocs_puml
diff --git a/docs/HowToHelp/images/github-pages-actions.png b/docs/HowToHelp/images/github-pages-actions.png
diff --git a/docs/HowToHelp/images/github-pages-branch.png b/docs/HowToHelp/images/github-pages-branch.png
diff --git a/docs/Installation/.pages b/docs/Installation/.pages
@@ -0,0 +1,8 @@
+title: Installation
+
+nav:
+    - Infrastructure Planning: InfrastructurePlanning.md
+    - Target Platforms: platform
+    - Installation Mechanisms: mechanism
+    - Tools you need: Tools.md
+    - Video Guides: Video_Guides.md