s+: update root files

.gitignore

@@ -1,9 +1,18 @@
+.idea/
 old/*
 
 # cached files
 __pycache__/
 *.py[cod]
 *$py.class
+.cache/
+
+# documentation
+docs/spow.sh
+docs/termux.sh
+docs/whatsapp.sh
+docs/telegram.sh
+/site
 
 # distribution
 .Python

CONTRIBUTORS

@@ -0,0 +1,2 @@
+Mark Joshwel <mark@joshwel.co>
+shamsu07 <shamsuddeenks@gmail.com>

README.md

@@ -4,25 +4,25 @@ surplus (s+) is a Python script to convert [Google Maps Plus Codes](https://maps
 to iOS Shortcuts-like shareable text
 
 - [quickstart](#quickstart)
-- [documentation](https://joshwel.co/surplus)
+- [documentation](https://surplus.joshwel.co)
-  - [the user's guide (command-line)](https://joshwel.co/surplus/using#as-a-command-line-tool)
+  - [the user's guide (command-line)](https://surplus.joshwel.co/using#as-a-command-line-tool)
-  - [the user's guide (library)](https://joshwel.co/surplus/using#as-a-library)
+  - [the user's guide (library)](https://surplus.joshwel.co/using#as-a-library)
-  - [the developer's guide](https://joshwel.co/surplus/developing)
+  - [the developer's guide](https://surplus.joshwel.co/developing)
-      - [api reference](https://joshwel.co/surplus/developing)
+      - [api reference](https://surplus.joshwel.co/developing)
-  - [the contributor's guide](https://joshwel.co/surplus/contributing)
+  - [the contributor's guide](https://surplus.joshwel.co/contributing)
 
 this repository is also monorepo for the following sibling projects:
 
-- **surplus on wheels** (s+ow) \
+- **surplus on wheels** (s+ow)  
   a pure shell script to get your location using `termux-location`, process it through surplus, and
   send it to messaging service or wherever, using "bridges"
-- **surplus on wheels: whatsapp bridge**
+- **surplus on wheels: Whatsapp Bridge**
-- **surplus on wheels: telegram bridge**
+- **surplus on wheels: Telegram Bridge**
 
 ## quickstart
 
 > [!TIP]  
-> termux users can consider [surplus on wheels](https://joshwel.co/surplus/onwheels), a sibling
+> termux users can consider [surplus on wheels](https://surplus.joshwel.co/onwheels), a sibling
 > project that allows you to run surplus regularly throughout the day and send it to someone on a
 > messaging platform
 
@@ -40,7 +40,7 @@ then, use the `surplus` command, or its `s+` shorthand:
 
 ```text
 $ s+ 7RGX+GJ Singapore
-surplus version 2024.0.0
+surplus version 2024.0.0-beta
 Singapore Conference Hall
 7 Shenton Way
 068809
@@ -49,52 +49,52 @@ Central, Singapore
 
 the types of queries you can pass in are:
 
-- full-length Plus Codes \
+- full-length Plus Codes  
   `6PH58QMF+FX`
-- shortened Plus Codes / 'local codes' \
+- shortened Plus Codes / 'local codes'  
   `8QMF+FX Singapore`
-- latitude and longitude coordinate pairs \
+- latitude and longitude coordinate pairs  
   `1.3336875, 103.7749375`
-- string queries \
+- string queries  
   `Wisma Atria`
 
 or, alternatively pass in `-` to read from stdin
 
-more documentation is available at <https://joshwel.co/surplus>,
+more documentation is available at <https://surplus.joshwel.co>,
 or alternatively available locally in the [docs/](docs) folder
 
 ## licences
 
-- [**surplus**](src/surplus) \
+- [**surplus**](src/surplus)  
   The Unlicence
 
   surplus is free and unencumbered software released into the public domain. for more information,
   please refer to the [UNLICENCE](src/surplus/UNLICENCE), <https://unlicense.org>, or the python
   module docstring
 
-  however, the direct dependencies surplus relies on are licenced under different, but still
+  however, the dependencies surplus relies on are licenced under different, but still permissive
-  permissive and open-source licences:
+  and open-source licences:
 
-    - **[geopy](https://pypi.org/project/geopy/)** — 
+    - [**geopy**](https://pypi.org/project/geopy/) — 
-      Python Geocoding Toolbox \
+      Python Geocoding Toolbox  
       MIT Licence
 
-        - **[geographiclib](https://pypi.org/project/geographiclib/)** — 
+        - [**geographiclib**](https://pypi.org/project/geographiclib/) — 
-          The geodesic routines from GeographicLib \
+          The geodesic routines from GeographicLib  
           MIT Licence
 
-    - **[pluscodes](https://pypi.org/project/pluscodes/)** — 
+    - [**pluscodes**](https://pypi.org/project/pluscodes/) — 
-      Compute Plus Codes (Open Location Codes) \
+      Compute Plus Codes (Open Location Codes)  
       Apache 2.0
 
-- [**surplus on wheels**](src/surplus-on-wheels) \
+- [**surplus on wheels**](src/surplus-on-wheels)  
   The Unlicence
 
   surplus on wheels is free and unencumbered software released into the public domain. for more
   information, please refer to [UNLICENCE](src/surplus-on-wheels/UNLICENCE) or
-  <https://unlicense.org/>
+  <http://unlicense.org/>
 
-- [**surplus on wheels: WhatsApp Bridge**](src/spow-whatsapp-bridge) \
+- [**surplus on wheels: WhatsApp Bridge**](src/spow-whatsapp-bridge)  
   Mozilla Public Licence 2.0
 
   the s+ow WhatsApp Bridge is based off mdtest code from the
@@ -106,10 +106,10 @@ or alternatively available locally in the [docs/](docs) folder
   permissive and open-source licences:
 
     - [**whatsmeow**](https://github.com/tulir/whatsmeow) — 
-      Go library for the WhatsApp web multidevice API \
+      Go library for the WhatsApp web multidevice API  
       Mozilla Public Licence 2.0
 
-- [**surplus on wheels: Telegram Bridge**](src/spow-telegram-bridge) \
+- [**surplus on wheels: Telegram Bridge**](src/spow-telegram-bridge)  
   The Unlicence
 
   the s+ow Telegram Bridge is free and unencumbered software released into the public domain. for
@@ -119,6 +119,30 @@ or alternatively available locally in the [docs/](docs) folder
   however, the direct dependencies surplus relies on are licenced under different, but still
   permissive and open-source licences:
 
-    - **[Telethon](https://github.com/LonamiWebs/Telethon)** — 
+    - [**Telethon**](https://pypi.org/project/Telethon/) — 
-      Pure Python 3 MTProto API Telegram client library, for bots too! \
+      Pure Python 3 MTProto API Telegram client library, for bots too!  
       MIT Licence
+
+- [**surplus documentation**](docs)  
+  CC0 1.0 Universal
+
+  the textual contents of surplus documentation by [Mark Joshwel](https://joshwel.co) is marked
+  with [CC0 1.0 Universal](https://creativecommons.org/publicdomain/zero/1.0/).
+  to view a copy of this license, visit <https://creativecommons.org/publicdomain/zero/1.0/>
+
+  the fonts the documentation website relies on are licenced under different, but still
+  permissive and open-source licences:
+
+    - [**Geist and Geist Mono**](https://github.com/vercel/geist-font)  
+      SIL Open Font Licence 1.1 ([file](docs/fonts/LICENSE.txt))
+    
+  the direct software dependencies the documentation are also licenced under different, but still
+  permissive and open-source licences:
+
+    - [**mkdocs-material**](https://squidfunk.github.io/mkdocs-material/) — 
+      Documentation that simply works  
+      MIT Licence
+
+    - [**mkdocs**](https://www.mkdocs.org/) — 
+      Project documentation with Markdown  
+      BSD-2-Clause Licence

pyproject.toml

@@ -42,10 +42,10 @@ exclude = [
 packages = ["src.surplus"]
 
 [project.urls]
-Documentation = "https://joshwel.co/surplus"
+Documentation = "https://surplus.joshwel.co"
-Issues = "https://joshwel.co/surplus/issues"
+Issues = "https://surplus.joshwel.co/issues"
 Source = "https://github.com/markjoshwel/surplus"
-Changelog = "https://joshwel.co/surplus/changelog"
+Changelog = "https://surplus.joshwel.co/changelog"
 
 [tool.ruff]
 line-length = 100
@@ -63,17 +63,17 @@ python = ["3.11", "3.12"]
 
 [tool.hatch.envs.default]
 description = "default development environment"
-dependencies = ["mypy", "isort"]
+dependencies = ["mypy", "ruff", "isort"]
 
 [tool.hatch.envs.default.scripts]
 check = [
-  "mypy *.py",
+  "mypy src",
   "hatch fmt --check",
-  "isort --check surplus"
+  "isort --check src"
 ]
 format = [
   "hatch fmt -f",
-  "isort surplus"
+  "isort src"
 ]
 
 [tool.hatch.envs.hatch-static-analysis]
@@ -83,8 +83,15 @@ dependencies = ["ruff>=0.3.2"]
 detached = true
 description = "env for generator documentation"
 dependencies = [
-  "mkdocs"
+  "mkdocs",
+  "mkdocs-material",
+  "mkdocs-git-revision-date-localized-plugin",
+  "mkdocs-exporter",
+  "playwright",
 ]
 [tool.hatch.envs.docs.scripts]
-build = "mkdocs build --clean --strict"
+build = [
+  "python src/tools/docs-prebuild.py",
+  "mkdocs build --clean --strict",
+]
 serve = "mkdocs serve --dev-addr localhost:8000"

src/tools/releaser.py

@@ -47,16 +47,22 @@ _insert_build_branch = getenv(
         capture_output=True,
         text=True,
         check=False,
-    ).stdout.strip("\n").strip(),
+    )
+    .stdout.strip("\n")
+    .strip(),
 )
 insert_build_branch = _insert_build_branch if _insert_build_branch != "" else "unknown"
 
-_insert_build_commit: str = run(
+_insert_build_commit: str = (
+    run(
         "git rev-parse HEAD".split(),
         capture_output=True,
         text=True,
         check=False,
-).stdout.strip("\n").strip()
+    )
+    .stdout.strip("\n")
+    .strip()
+)
 insert_build_commit = _insert_build_commit if _insert_build_commit != "" else "unknown"
 
 insert_build_datetime: str = repr(build_time).replace("datetime.", "")