docs: add mkdocs site :O
This commit is contained in:
parent
40d318bef7
commit
c6eadc6045
121
docs/CC0
Normal file
121
docs/CC0
Normal file
|
|
@ -0,0 +1,121 @@
|
||||||
|
Creative Commons Legal Code
|
||||||
|
|
||||||
|
CC0 1.0 Universal
|
||||||
|
|
||||||
|
CREATIVE COMMONS CORPORATION IS NOT A LAW FIRM AND DOES NOT PROVIDE
|
||||||
|
LEGAL SERVICES. DISTRIBUTION OF THIS DOCUMENT DOES NOT CREATE AN
|
||||||
|
ATTORNEY-CLIENT RELATIONSHIP. CREATIVE COMMONS PROVIDES THIS
|
||||||
|
INFORMATION ON AN "AS-IS" BASIS. CREATIVE COMMONS MAKES NO WARRANTIES
|
||||||
|
REGARDING THE USE OF THIS DOCUMENT OR THE INFORMATION OR WORKS
|
||||||
|
PROVIDED HEREUNDER, AND DISCLAIMS LIABILITY FOR DAMAGES RESULTING FROM
|
||||||
|
THE USE OF THIS DOCUMENT OR THE INFORMATION OR WORKS PROVIDED
|
||||||
|
HEREUNDER.
|
||||||
|
|
||||||
|
Statement of Purpose
|
||||||
|
|
||||||
|
The laws of most jurisdictions throughout the world automatically confer
|
||||||
|
exclusive Copyright and Related Rights (defined below) upon the creator
|
||||||
|
and subsequent owner(s) (each and all, an "owner") of an original work of
|
||||||
|
authorship and/or a database (each, a "Work").
|
||||||
|
|
||||||
|
Certain owners wish to permanently relinquish those rights to a Work for
|
||||||
|
the purpose of contributing to a commons of creative, cultural and
|
||||||
|
scientific works ("Commons") that the public can reliably and without fear
|
||||||
|
of later claims of infringement build upon, modify, incorporate in other
|
||||||
|
works, reuse and redistribute as freely as possible in any form whatsoever
|
||||||
|
and for any purposes, including without limitation commercial purposes.
|
||||||
|
These owners may contribute to the Commons to promote the ideal of a free
|
||||||
|
culture and the further production of creative, cultural and scientific
|
||||||
|
works, or to gain reputation or greater distribution for their Work in
|
||||||
|
part through the use and efforts of others.
|
||||||
|
|
||||||
|
For these and/or other purposes and motivations, and without any
|
||||||
|
expectation of additional consideration or compensation, the person
|
||||||
|
associating CC0 with a Work (the "Affirmer"), to the extent that he or she
|
||||||
|
is an owner of Copyright and Related Rights in the Work, voluntarily
|
||||||
|
elects to apply CC0 to the Work and publicly distribute the Work under its
|
||||||
|
terms, with knowledge of his or her Copyright and Related Rights in the
|
||||||
|
Work and the meaning and intended legal effect of CC0 on those rights.
|
||||||
|
|
||||||
|
1. Copyright and Related Rights. A Work made available under CC0 may be
|
||||||
|
protected by copyright and related or neighboring rights ("Copyright and
|
||||||
|
Related Rights"). Copyright and Related Rights include, but are not
|
||||||
|
limited to, the following:
|
||||||
|
|
||||||
|
i. the right to reproduce, adapt, distribute, perform, display,
|
||||||
|
communicate, and translate a Work;
|
||||||
|
ii. moral rights retained by the original author(s) and/or performer(s);
|
||||||
|
iii. publicity and privacy rights pertaining to a person's image or
|
||||||
|
likeness depicted in a Work;
|
||||||
|
iv. rights protecting against unfair competition in regards to a Work,
|
||||||
|
subject to the limitations in paragraph 4(a), below;
|
||||||
|
v. rights protecting the extraction, dissemination, use and reuse of data
|
||||||
|
in a Work;
|
||||||
|
vi. database rights (such as those arising under Directive 96/9/EC of the
|
||||||
|
European Parliament and of the Council of 11 March 1996 on the legal
|
||||||
|
protection of databases, and under any national implementation
|
||||||
|
thereof, including any amended or successor version of such
|
||||||
|
directive); and
|
||||||
|
vii. other similar, equivalent or corresponding rights throughout the
|
||||||
|
world based on applicable law or treaty, and any national
|
||||||
|
implementations thereof.
|
||||||
|
|
||||||
|
2. Waiver. To the greatest extent permitted by, but not in contravention
|
||||||
|
of, applicable law, Affirmer hereby overtly, fully, permanently,
|
||||||
|
irrevocably and unconditionally waives, abandons, and surrenders all of
|
||||||
|
Affirmer's Copyright and Related Rights and associated claims and causes
|
||||||
|
of action, whether now known or unknown (including existing as well as
|
||||||
|
future claims and causes of action), in the Work (i) in all territories
|
||||||
|
worldwide, (ii) for the maximum duration provided by applicable law or
|
||||||
|
treaty (including future time extensions), (iii) in any current or future
|
||||||
|
medium and for any number of copies, and (iv) for any purpose whatsoever,
|
||||||
|
including without limitation commercial, advertising or promotional
|
||||||
|
purposes (the "Waiver"). Affirmer makes the Waiver for the benefit of each
|
||||||
|
member of the public at large and to the detriment of Affirmer's heirs and
|
||||||
|
successors, fully intending that such Waiver shall not be subject to
|
||||||
|
revocation, rescission, cancellation, termination, or any other legal or
|
||||||
|
equitable action to disrupt the quiet enjoyment of the Work by the public
|
||||||
|
as contemplated by Affirmer's express Statement of Purpose.
|
||||||
|
|
||||||
|
3. Public License Fallback. Should any part of the Waiver for any reason
|
||||||
|
be judged legally invalid or ineffective under applicable law, then the
|
||||||
|
Waiver shall be preserved to the maximum extent permitted taking into
|
||||||
|
account Affirmer's express Statement of Purpose. In addition, to the
|
||||||
|
extent the Waiver is so judged Affirmer hereby grants to each affected
|
||||||
|
person a royalty-free, non transferable, non sublicensable, non exclusive,
|
||||||
|
irrevocable and unconditional license to exercise Affirmer's Copyright and
|
||||||
|
Related Rights in the Work (i) in all territories worldwide, (ii) for the
|
||||||
|
maximum duration provided by applicable law or treaty (including future
|
||||||
|
time extensions), (iii) in any current or future medium and for any number
|
||||||
|
of copies, and (iv) for any purpose whatsoever, including without
|
||||||
|
limitation commercial, advertising or promotional purposes (the
|
||||||
|
"License"). The License shall be deemed effective as of the date CC0 was
|
||||||
|
applied by Affirmer to the Work. Should any part of the License for any
|
||||||
|
reason be judged legally invalid or ineffective under applicable law, such
|
||||||
|
partial invalidity or ineffectiveness shall not invalidate the remainder
|
||||||
|
of the License, and in such case Affirmer hereby affirms that he or she
|
||||||
|
will not (i) exercise any of his or her remaining Copyright and Related
|
||||||
|
Rights in the Work or (ii) assert any associated claims and causes of
|
||||||
|
action with respect to the Work, in either case contrary to Affirmer's
|
||||||
|
express Statement of Purpose.
|
||||||
|
|
||||||
|
4. Limitations and Disclaimers.
|
||||||
|
|
||||||
|
a. No trademark or patent rights held by Affirmer are waived, abandoned,
|
||||||
|
surrendered, licensed or otherwise affected by this document.
|
||||||
|
b. Affirmer offers the Work as-is and makes no representations or
|
||||||
|
warranties of any kind concerning the Work, express, implied,
|
||||||
|
statutory or otherwise, including without limitation warranties of
|
||||||
|
title, merchantability, fitness for a particular purpose, non
|
||||||
|
infringement, or the absence of latent or other defects, accuracy, or
|
||||||
|
the present or absence of errors, whether or not discoverable, all to
|
||||||
|
the greatest extent permissible under applicable law.
|
||||||
|
c. Affirmer disclaims responsibility for clearing rights of other persons
|
||||||
|
that may apply to the Work or any use thereof, including without
|
||||||
|
limitation any person's Copyright and Related Rights in the Work.
|
||||||
|
Further, Affirmer disclaims responsibility for obtaining any necessary
|
||||||
|
consents, permissions or other rights required for any use of the
|
||||||
|
Work.
|
||||||
|
d. Affirmer understands and acknowledges that Creative Commons is not a
|
||||||
|
party to this document and has no duty or obligation with respect to
|
||||||
|
this CC0 or use of the Work.
|
||||||
325
docs/changelog.md
Normal file
325
docs/changelog.md
Normal file
|
|
@ -0,0 +1,325 @@
|
||||||
|
# changelog
|
||||||
|
|
||||||
|
## surplus v2024.0.0
|
||||||
|
|
||||||
|
(unreleased)
|
||||||
|
|
||||||
|
!!! information
|
||||||
|
this is a tentative release. surplus is currently versioned as `2024.0.0-beta`, as its
|
||||||
|
behaviour is not stabilized
|
||||||
|
|
||||||
|
!!! warning
|
||||||
|
this is an api-breaking release. see 'the great api break'.
|
||||||
|
command-line usage of surplus has not changed
|
||||||
|
|
||||||
|
### what's new
|
||||||
|
|
||||||
|
- added flag `--show-user-agent`, printing the fingerprinted user agent string and exiting
|
||||||
|
|
||||||
|
### what's changed
|
||||||
|
|
||||||
|
- `default_geocoder()` and `default_reverser()` have been deprecated since v2.1.0 and are now
|
||||||
|
removed. use the `SurplusDefaultGeocoding` class instead
|
||||||
|
- `SurplusException` is now `SurplusError`
|
||||||
|
|
||||||
|
### the great api break
|
||||||
|
|
||||||
|
TODO
|
||||||
|
|
||||||
|
### thanks!
|
||||||
|
|
||||||
|
- [vlshields](https://github.com/vlshields/) for their support with a drink!
|
||||||
|
|
||||||
|
full changelog: <https://github.com/markjoshwel/surplus/compare/v2.2.0...v2024.0.0>
|
||||||
|
|
||||||
|
## surplus on wheels v2
|
||||||
|
|
||||||
|
(released on the 1st of July 2024 on tag `v2.2024.25+spow`)
|
||||||
|
|
||||||
|
### changes
|
||||||
|
|
||||||
|
- you can now customize command invocations with `SURPLUS_CMD` and `LOCATION_CMD` environment variables
|
||||||
|
- surplus on wheels will purge logs when setting the `SPOW_PRIVATE` environment flag
|
||||||
|
|
||||||
|
### thanks!
|
||||||
|
|
||||||
|
- [vlshields](https://github.com/vlshields/) for their support with a drink!
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## surplus on wheels: WhatsApp Bridge v2.2024.25
|
||||||
|
|
||||||
|
(released on the 17th of June 2024 on tag `v2.2024.25+spow-whatsapp-bridge`)
|
||||||
|
|
||||||
|
!!! note
|
||||||
|
from henceforth, the WhatsApp Bridge is now versioned with a modified calendar versioning scheme
|
||||||
|
of `MAJOR.YEAR.ISOWEEK`, where the `MAJOR` version segment will be bumped with codebase changes,
|
||||||
|
whereas the `YEAR` and `ISOWEEK` segments will represent the time of which the release was
|
||||||
|
built at
|
||||||
|
|
||||||
|
### changes
|
||||||
|
|
||||||
|
- updated dependencies to latest versions
|
||||||
|
- added `pair-phone` and `reconnect` subcommands
|
||||||
|
- TODO added optional helper script to auto-update to newer versions via a user-made daily cron job
|
||||||
|
|
||||||
|
### thanks!
|
||||||
|
|
||||||
|
- [vlshields](https://github.com/vlshields/) for their support with a drink!
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## surplus on wheels: Telegram Bridge v2.2024.25
|
||||||
|
|
||||||
|
(released on the 17th of June 2024 on tag `v2.2024.25+spow-telegram-bridge`)
|
||||||
|
|
||||||
|
!!! note
|
||||||
|
from henceforth, the Telegram Bridge will automatically release a new version once a week if
|
||||||
|
there are updates to its dependencies
|
||||||
|
|
||||||
|
as such, the bridge is now versioned with a modified calendar versioning scheme of
|
||||||
|
`MAJOR.YEAR.ISOWEEK`, where the `MAJOR` version segment will be bumped with codebase changes,
|
||||||
|
whereas the `YEAR` and `ISOWEEK` segments will represent the time of which the release was
|
||||||
|
built at
|
||||||
|
|
||||||
|
### changes
|
||||||
|
|
||||||
|
- updated dependencies to latest versions
|
||||||
|
- added `logout` subcommand
|
||||||
|
- TODO added optional helper script to auto-update to newer versions via a user-made daily cron job
|
||||||
|
|
||||||
|
### thanks!
|
||||||
|
|
||||||
|
- [vlshields](https://github.com/vlshields/) for their support with a drink!
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## surplus on wheels v1
|
||||||
|
|
||||||
|
initial release on the 9th of November 2023
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## surplus on wheels: WhatsApp Bridge v1
|
||||||
|
|
||||||
|
initial release on the 7th of November 2023
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## surplus on wheels: Telegram Bridge v1
|
||||||
|
|
||||||
|
initial release on the 7th of November 2023
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## surplus v2.2.0
|
||||||
|
|
||||||
|
(released on the 14th of October 2023)
|
||||||
|
|
||||||
|
!!! warning
|
||||||
|
constants are changed in this update!
|
||||||
|
|
||||||
|
fixed a bug installing surplus on Python 3.12 and italian sharetext fixes
|
||||||
|
|
||||||
|
### what's new
|
||||||
|
|
||||||
|
- special key arrangements for malaysia
|
||||||
|
- support for termux-location json input
|
||||||
|
|
||||||
|
### what's fixed
|
||||||
|
|
||||||
|
- fixed typing-extensions as an unwritten dependency
|
||||||
|
this also fixes a bug in not being able to run surplus in Python 3.12
|
||||||
|
- fixed italian key arrangements [#34](https://github.com/markjoshwel/surplus/pull/34)
|
||||||
|
|
||||||
|
### what's changed
|
||||||
|
|
||||||
|
- **`SHAREABLE*` constants are now dictionaries, see api docs for more information**
|
||||||
|
|
||||||
|
<https://github.com/markjoshwel/surplus/compare/v2.1.1...v2.2.0>
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## surplus v2.1.1
|
||||||
|
|
||||||
|
(released on the 19th of September 2023)
|
||||||
|
|
||||||
|
fix roads not coming first in Italian addresses (#31)
|
||||||
|
|
||||||
|
- documentation enhancements
|
||||||
|
- remove self in `SurplusReverserProtocol` conforming signature
|
||||||
|
- fix mismatching carets and add info on `split_iso3166_2`
|
||||||
|
- alternative line 3 arrangement for IT/Italy in [#31](https://github.com/markjoshwel/surplus/pull/31)
|
||||||
|
|
||||||
|
<https://github.com/markjoshwel/surplus/compare/v2.1.0...v2.1.1>
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## surplus v2.1.0
|
||||||
|
|
||||||
|
(released on the 6th of September 2023)
|
||||||
|
|
||||||
|
!!! warning
|
||||||
|
there are backwards-compatible api changes in this release.
|
||||||
|
|
||||||
|
type-to-type location representation conversions and quality of life changes/fixes
|
||||||
|
|
||||||
|
- **`default_geocoder()` and `default_reverser()` functions have been deprecated in favour of the
|
||||||
|
new [`SurplusDefaultGeocoding` class](https://github.com/markjoshwel/surplus/tree/main#class-surplusdefaultgeocoding)**
|
||||||
|
- add reading from stdin when query is "-" in [#23](https://github.com/markjoshwel/surplus/pull/23)
|
||||||
|
- type to type conversion in [#24](https://github.com/markjoshwel/surplus/pull/24)
|
||||||
|
- fix local codes not being recognised if split with comma in [#29](https://github.com/markjoshwel/surplus/pull/29)
|
||||||
|
- more verbose -v/--version information in [#21](https://github.com/markjoshwel/surplus/pull/21)
|
||||||
|
|
||||||
|
<https://github.com/markjoshwel/surplus/compare/v2.0.1...v2.1.0>
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## surplus v2.0.1
|
||||||
|
|
||||||
|
(released on the 5th of September 2023)
|
||||||
|
|
||||||
|
- expose surplus.Result in `__init__.py` by in [#28](https://github.com/markjoshwel/surplus/pull/28)
|
||||||
|
|
||||||
|
<https://github.com/markjoshwel/surplus/compare/v2.0.0...v2.0.1>
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## surplus v2.0.0
|
||||||
|
|
||||||
|
(released on the 3rd of September 2023)
|
||||||
|
|
||||||
|
!!! warning
|
||||||
|
this is an api-breaking release. see 'the great api break'.
|
||||||
|
command-line usage of surplus has not changed
|
||||||
|
|
||||||
|
!!! information
|
||||||
|
python 3.11 or later is required due to a bug in earlier versions
|
||||||
|
[(python/cpython#88089)](https://github.com/python/cpython/issues/88089)
|
||||||
|
|
||||||
|
complete rewrite and string query support
|
||||||
|
|
||||||
|
### changes
|
||||||
|
|
||||||
|
- surplus has been fully rewritten in [#19](https://github.com/markjoshwel/surplus/pull/19)
|
||||||
|
- support for string queries
|
||||||
|
```text
|
||||||
|
$ s+ Wisma Atria
|
||||||
|
surplus version 2.0.0
|
||||||
|
Wisma Atria
|
||||||
|
435 Orchard Road
|
||||||
|
238877
|
||||||
|
Central, Singapore
|
||||||
|
```
|
||||||
|
- mypy will now recognise surplus as a typed module
|
||||||
|
- **python 3.11 is now the minimum version**
|
||||||
|
|
||||||
|
### the great api break
|
||||||
|
|
||||||
|
#### what is new
|
||||||
|
|
||||||
|
- nominatim keys are now stored in tuple constants
|
||||||
|
- surplus exception classes are now a thing
|
||||||
|
- surplus functions now operate using a unified `Behaviour` object
|
||||||
|
- surplus functions now return a `Result` object for safer value retrieval instead of the previous
|
||||||
|
`(bool, value)` tuple
|
||||||
|
- dedicated NamedTuple classes for each query type
|
||||||
|
|
||||||
|
#### what has been removed
|
||||||
|
|
||||||
|
- `surplus.handle_query()`
|
||||||
|
|
||||||
|
instead, use `.to_lat_long_coord()` on your surplus 2.x query object
|
||||||
|
|
||||||
|
#### what has remained
|
||||||
|
|
||||||
|
- `surplus.surplus()`, the function
|
||||||
|
- `surplus.parse_query()`, the function
|
||||||
|
|
||||||
|
#### what has changed
|
||||||
|
|
||||||
|
- `surplus.surplus()`
|
||||||
|
1. `reverser` and `debug` arguments are now under the unified `surplus.Behaviour` object
|
||||||
|
2. function now returns a `surplus.Result[str]` for safer error handling
|
||||||
|
|
||||||
|
- `surplus.parse_query()`
|
||||||
|
1. `query` and `debug` arguments are now under the unified `surplus.Behaviour` object
|
||||||
|
2. function now returns a `surplus.Result[surplus.Query]` for safer error handling
|
||||||
|
|
||||||
|
- `surplus.Latlong`
|
||||||
|
attributes `lat` and `long` have been renamed to `latitude` and `longitude` respectively
|
||||||
|
|
||||||
|
- `surplus.Localcode`
|
||||||
|
renamed to `surplus.LocalCodeQuery`
|
||||||
|
|
||||||
|
- `Localcode.full_length()`
|
||||||
|
renamed to `LocalCodeQuery.to_full_plus_code()`, and returns a `surplus.Result[str]` for safer
|
||||||
|
error handling
|
||||||
|
|
||||||
|
full changelog: <https://github.com/markjoshwel/surplus/compare/v1.1.3...v2.0.0>
|
||||||
|
|
||||||
|
## surplus v1.1.3
|
||||||
|
|
||||||
|
(released on the 21st of June 2023)
|
||||||
|
|
||||||
|
general output fixes and quality of life updates
|
||||||
|
|
||||||
|
- ci(qc) workflow tweaks by [markjoshwel](https://github.com/markjoshwel) in [#13](https://github.com/markjoshwel/surplus/pull/13)
|
||||||
|
- cc: remove woodlands test + brackets by [markjoshwel](https://github.com/markjoshwel) in [#14](https://github.com/markjoshwel/surplus/pull/14)
|
||||||
|
- s+: display county before state by [markjoshwel](https://github.com/markjoshwel) in [#15](https://github.com/markjoshwel/surplus/pull/15)
|
||||||
|
|
||||||
|
<https://github.com/markjoshwel/surplus/compare/v1.1.2...v1.1.3>
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## surplus v1.1.2
|
||||||
|
|
||||||
|
(released on the 18th of June 2023)
|
||||||
|
|
||||||
|
general output fixes and quality of life updates
|
||||||
|
|
||||||
|
- do not repeat details by [markjoshwel](https://github.com/markjoshwel) in #9
|
||||||
|
- add -v/--version flag by [markjoshwel](https://github.com/markjoshwel) in #11
|
||||||
|
|
||||||
|
<https://github.com/markjoshwel/surplus/compare/v1.1.0...v1.1.1>
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## surplus v1.1.1
|
||||||
|
|
||||||
|
(released on the 16th of June 2023)
|
||||||
|
|
||||||
|
### changes
|
||||||
|
|
||||||
|
fixes and output tweaks
|
||||||
|
|
||||||
|
- fix reverser returning a None location by [shamsu07](https://github.com/shamsu07) in #5
|
||||||
|
|
||||||
|
### thanks!
|
||||||
|
|
||||||
|
- [shamsu07](https://github.com/shamsu07) made their first contribution!
|
||||||
|
|
||||||
|
<https://github.com/markjoshwel/surplus/compare/v1.1.0...v1.1.1>
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## surplus v1.1.0
|
||||||
|
|
||||||
|
(released on the 3rd of June 2023)
|
||||||
|
|
||||||
|
short code and latitude longitude coordinate pair support!
|
||||||
|
|
||||||
|
- code: s+ alternative shorthand script
|
||||||
|
- code: handle none/list locations
|
||||||
|
- code: query by lat long support
|
||||||
|
- code: support shortcodes with localities
|
||||||
|
- code: implement more address detail tags from nominatim
|
||||||
|
- meta: slsa 3 compliance
|
||||||
|
|
||||||
|
<https://github.com/markjoshwel/surplus/compare/v1.0.0...v1.1.0>
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## surplus v1.0.0
|
||||||
|
|
||||||
|
initial release on the 2nd of June 2023
|
||||||
80
docs/contributing.md
Normal file
80
docs/contributing.md
Normal file
|
|
@ -0,0 +1,80 @@
|
||||||
|
# the contributor's handbook
|
||||||
|
|
||||||
|
expected details on development workflows? see [the developer's handbook](developing.md)
|
||||||
|
|
||||||
|
## which forge do i use?
|
||||||
|
|
||||||
|
as at the time of writing this documentation, i am actively using both
|
||||||
|
<https://github.com/markjoshwel/surplus> and <https://forge.joshwel.co/mark/surplus>
|
||||||
|
|
||||||
|
use whatever is more comfortable to you. do you not like microsoft and/or have moved away from github?
|
||||||
|
feel free to use <https://forge.joshwel.co>. don't want to make an account for either? did the forge
|
||||||
|
implode and is down? okay! mail in a git patch at <mark@joshwel.co>
|
||||||
|
|
||||||
|
## git workflow
|
||||||
|
|
||||||
|
1. fork the repository and branch off from the `future` branch,
|
||||||
|
or `main` if not available
|
||||||
|
2. make and commit your changes!
|
||||||
|
3. pull in any changes from upstream, and resolve any conflicts, if any
|
||||||
|
4. if needed, **commit your copyright waiver** (_see [waiving copyright](#waiving-copyright)_)
|
||||||
|
5. submit a pull request (_or mail in a patch_)
|
||||||
|
|
||||||
|
### waiving copyright
|
||||||
|
|
||||||
|
!!! danger "Warning"
|
||||||
|
this section is a **must** to follow if you have modified **any** unlicenced code:
|
||||||
|
|
||||||
|
- top-level surplus files (`releaser.py`, etc)
|
||||||
|
- surplus (`src/surplus`)
|
||||||
|
- surplus Documentation (`docs/`)
|
||||||
|
- surplus on wheels (`src/surplus-on-wheels`)
|
||||||
|
- surplus on wheels: Telegram Bridge (`src/spow-telegram-bridge`)
|
||||||
|
|
||||||
|
!!! info
|
||||||
|
the command to create an empty commit is `git commit --allow-empty`
|
||||||
|
|
||||||
|
when contributing your first changes, please include an empty commit for a copyright
|
||||||
|
waiver using the following message (replace `Your Name` with your name or username):
|
||||||
|
|
||||||
|
```text
|
||||||
|
Your Name Copyright Waiver
|
||||||
|
|
||||||
|
I dedicate any and all copyright interest in this software to the
|
||||||
|
public domain. I make this dedication for the benefit of the public at
|
||||||
|
large and to the detriment of my heirs and successors. I intend this
|
||||||
|
dedication to be an overt act of relinquishment in perpetuity of all
|
||||||
|
present and future rights to this software under copyright law.
|
||||||
|
|
||||||
|
To the best of my knowledge and belief, my contributions are either
|
||||||
|
originally authored by me or are derived from prior works which I have
|
||||||
|
verified are also in the public domain and are not subject to claims
|
||||||
|
of copyright by other parties.
|
||||||
|
|
||||||
|
To the best of my knowledge and belief, no individual, business,
|
||||||
|
organization, government, or other entity has any copyright interest
|
||||||
|
in my contributions, and I affirm that I will not make contributions
|
||||||
|
that are otherwise encumbered.
|
||||||
|
```
|
||||||
|
|
||||||
|
(from <https://unlicense.org/WAIVER>)
|
||||||
|
|
||||||
|
for documentation contributors, if you have contributed a
|
||||||
|
[legally significant](https://www.gnu.org/prep/maintain/maintain.html#Legally-Significant) or have
|
||||||
|
repeatedly commited multiple small changes, waive your copyright with the CC0 deed
|
||||||
|
(replace `Your Name` with your name or username):
|
||||||
|
|
||||||
|
```text
|
||||||
|
Your Name Copyright Waiver
|
||||||
|
|
||||||
|
The person who associated a work with this deed has dedicated the work to
|
||||||
|
the public domain by waiving all of his or her rights to the work worldwide
|
||||||
|
under copyright law, including all related and neighboring rights, to the
|
||||||
|
extent allowed by law.
|
||||||
|
```
|
||||||
|
|
||||||
|
(from <https://creativecommons.org/publicdomain/zero/1.0/>)
|
||||||
|
|
||||||
|
## reporting incorrect output
|
||||||
|
|
||||||
|
TODO
|
||||||
319
docs/developing.md
Normal file
319
docs/developing.md
Normal file
|
|
@ -0,0 +1,319 @@
|
||||||
|
# the developer’s handbook
|
||||||
|
|
||||||
|
!!! abstract
|
||||||
|
i (mark), heavily use nix to manage my projects, either with
|
||||||
|
[devbox](https://github.com/jetpack-io/devbox) or flakes
|
||||||
|
|
||||||
|
if you are going to develop for surplus or its' sibling projects (except surplus on wheels,
|
||||||
|
which only needs `shfmt` and `shellcheck`), i would recommend you install Nix using
|
||||||
|
[Determinate Systems' Nix Installer](https://github.com/DeterminateSystems/nix-installer):
|
||||||
|
|
||||||
|
```text
|
||||||
|
curl --proto '=https' --tlsv1.2 -sSf -L https://install.determinate.systems/nix | sh -s -- install
|
||||||
|
```
|
||||||
|
|
||||||
|
if i, a very very inexperienced Nix and NixOS user to give a rundown on why to use it:
|
||||||
|
|
||||||
|
1. **environments and builds are reproducible**
|
||||||
|
|
||||||
|
nix is part package manager, operating system (as NixOS), and functional programming
|
||||||
|
language. because it's functional, having X as an input will always produce Y as an output,
|
||||||
|
no matter what. even in the event of environmental, social, economic, or structural collapse
|
||||||
|
|
||||||
|
**what does this mean for you?**
|
||||||
|
when i use `nix develop` and you use `nix develop` to start a development environment, your
|
||||||
|
version of python will be the same as my version of python. your version of go will be same
|
||||||
|
as my version of go, etc
|
||||||
|
|
||||||
|
if i can build it, and the locked inputs of the nix flake are still available on the internet,
|
||||||
|
you can build it too
|
||||||
|
|
||||||
|
2. **the nix store**, located literally at `/nix/store`
|
||||||
|
it's where it stores every package you need, separate and isolated from other packages.
|
||||||
|
lets say you have a tool that needs python (3.8), and another tool that needs python (3.11).
|
||||||
|
nix store will download and store the binaries for both python installations, instead of
|
||||||
|
sharing the earliest downloaded python version for both tools
|
||||||
|
|
||||||
|
**what does this mean for you?**
|
||||||
|
whatever project you're working on that can use nix for development environments and builds
|
||||||
|
will not dirty anything else on your system. any build dependencies of surplus provided with
|
||||||
|
`nix develop` will **not** mess up software installed for other projects or even the system.
|
||||||
|
neat, if you ask me tbh
|
||||||
|
|
||||||
|
**tl;dr**: things will just werk with nix. but if you see all of this and go, "eh. i can manage
|
||||||
|
what i install.", then power to you! i list down exactly what prerequisite software needs to be
|
||||||
|
installed for each project anyways, so have fun! (●'◡'●)
|
||||||
|
|
||||||
|
## surplus (and Documentation)
|
||||||
|
|
||||||
|
### environment setup
|
||||||
|
|
||||||
|
!!! note
|
||||||
|
all prerequisite software are available in a nix flake. if you want a reproducible environment,
|
||||||
|
run `nix develop --impure` in the repository root
|
||||||
|
|
||||||
|
- for NixOS users, [nix-ld](https://github.com/Mic92/nix-ld) is needed. if you use flakes to
|
||||||
|
declare your system, follow accordingly. else, use `/etc/nixos/configuration.nix`
|
||||||
|
|
||||||
|
for NixOS-on-WSL users, use [nix-ld-rs](https://github.com/nix-community/nix-ld-rs)
|
||||||
|
|
||||||
|
once you're done installing `nix-ld` or `nix-ld-rs`,
|
||||||
|
don't forget to run `sudo nixos-rebuild switch`
|
||||||
|
|
||||||
|
prerequisite software:
|
||||||
|
|
||||||
|
- [Python](https://www.python.org/downloads/), 3.11 or newer
|
||||||
|
- [Hatch](https://hatch.pypa.io/latest/): dependency management and build tool
|
||||||
|
|
||||||
|
to start a development environment:
|
||||||
|
|
||||||
|
```text
|
||||||
|
hatch shell
|
||||||
|
```
|
||||||
|
|
||||||
|
for docs:
|
||||||
|
|
||||||
|
```text
|
||||||
|
hatch -e docs shell
|
||||||
|
```
|
||||||
|
|
||||||
|
### workflow for python code
|
||||||
|
|
||||||
|
TODO
|
||||||
|
|
||||||
|
### workflow for markdown documentation
|
||||||
|
|
||||||
|
run the documentation server with:
|
||||||
|
|
||||||
|
```text
|
||||||
|
hatch run docs:serve
|
||||||
|
```
|
||||||
|
|
||||||
|
i personally don't use a linter for markdown files, if it looks good on my code editor, then
|
||||||
|
whatever. if you're going to contribute back, i ask for three things:
|
||||||
|
|
||||||
|
- run it through a spell checker or something similar
|
||||||
|
|
||||||
|
- line limit of 100
|
||||||
|
|
||||||
|
- should be readable as-is on a code editor, **not the markdown preview pane**.
|
||||||
|
|
||||||
|
my stance is, if you can afford a fancy preview of the markdown file, use the nice-ned
|
||||||
|
documentation website. else, read it as a plaintext file
|
||||||
|
|
||||||
|
(make it look pretty on the doc site and in plaintext)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## surplus on wheels
|
||||||
|
|
||||||
|
### environment setup
|
||||||
|
|
||||||
|
!!! note
|
||||||
|
all prerequisite software are available in a nix flake. if you want a reproducible environment,
|
||||||
|
run `nix develop` in `src/surplus-on-wheels`
|
||||||
|
|
||||||
|
prerequisite software:
|
||||||
|
|
||||||
|
- [shfmt](https://github.com/patrickvane/shfmt): formatter
|
||||||
|
- [ShellCheck](https://www.shellcheck.net/): static analyser
|
||||||
|
|
||||||
|
### workflow
|
||||||
|
|
||||||
|
- formatting s+ow:
|
||||||
|
- run `shfmt s+ow > s+ow.new`
|
||||||
|
- mv `s+ow.new` into `s+ow`
|
||||||
|
sometimes when piping shfmt's output immediately into the same file
|
||||||
|
results in the file being empty :(
|
||||||
|
|
||||||
|
- checking s+ow:
|
||||||
|
- run `shellcheck s+ow`
|
||||||
|
if there's no output, that means it passed :)
|
||||||
|
|
||||||
|
- if commiting back into the repository, try it out on your Termux system for a day or two,
|
||||||
|
just to make sure it runs correctly
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## surplus on wheels: Telegram Bridge
|
||||||
|
|
||||||
|
### environment setup
|
||||||
|
|
||||||
|
!!! note
|
||||||
|
all prerequisite software are available in a nix flake. if you want a reproducible environment,
|
||||||
|
run `nix develop` in `src/spow-telegram-bridge`. it uses
|
||||||
|
[poetry2nix](https://github.com/nix-community/poetry2nix), so you won't need to run
|
||||||
|
`poetry shell` afterwards. if you've changed the `pyproject.toml` file,
|
||||||
|
just exit and re-run `nix develop`
|
||||||
|
|
||||||
|
prerequisite software:
|
||||||
|
|
||||||
|
- [Python](https://www.python.org/downloads/), 3.11 or newer
|
||||||
|
- [Poetry](https://python-poetry.org/): dependency management and build tool
|
||||||
|
|
||||||
|
to start a development environment:
|
||||||
|
|
||||||
|
```text
|
||||||
|
poetry shell
|
||||||
|
```
|
||||||
|
|
||||||
|
### workflow
|
||||||
|
|
||||||
|
after modifying,
|
||||||
|
|
||||||
|
1. `mypy bridge.py`
|
||||||
|
2. `ruff format bridge.py`
|
||||||
|
3. `ruff check bridge.py`
|
||||||
|
4. [test the binary](#workflow-for-testing-the-binary)
|
||||||
|
|
||||||
|
if the bridge behaves nominally, [bump the version](#versioning-surplus-on-wheels-telegram-bridge)
|
||||||
|
and commit!
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## surplus on wheels: WhatsApp Bridge
|
||||||
|
|
||||||
|
### environment setup
|
||||||
|
|
||||||
|
!!! note
|
||||||
|
all prerequisite software are available in a nix flake. if you want a reproducible environment,
|
||||||
|
run `nix develop` in `src/spow-whatsapp-bridge`
|
||||||
|
|
||||||
|
the flake will pull in the Android SDK and NDK for building on Termux, and as such can only be
|
||||||
|
ran on `x86_64-linux` and `x86_64-darwin`
|
||||||
|
|
||||||
|
prerequisite software:
|
||||||
|
|
||||||
|
- [Go](https://go.dev): 1.22 or newer
|
||||||
|
- [Android NDK](https://developer.android.com/ndk/downloads), if building for Termux
|
||||||
|
|
||||||
|
### workflow for modifying bridge code
|
||||||
|
|
||||||
|
the bridge's code is just modified [mdtest](https://github.com/tulir/whatsmeow/tree/main/mdtest)
|
||||||
|
code, and as such, whenever in doubt, do a diff between mdtest and the bridge code
|
||||||
|
|
||||||
|
after modifying,
|
||||||
|
|
||||||
|
1. [build a binary](#workflow-for-building-a-binary)
|
||||||
|
2. [test the binary](#workflow-for-testing-the-binary)
|
||||||
|
3. and if all goes well, [bump the version](#versioning-surplus-on-wheels-whatsapp-bridge)
|
||||||
|
and commit!
|
||||||
|
|
||||||
|
### workflow for bumping dependencies
|
||||||
|
|
||||||
|
- check with your editor, plugin, or online if there's newer patch/minor (see
|
||||||
|
[semantic versioning](https://semver.org/)) versions to update to
|
||||||
|
|
||||||
|
- change the `go.mod` accordingly
|
||||||
|
|
||||||
|
after bumping,
|
||||||
|
|
||||||
|
1. [build a binary](#workflow-for-building-a-binary)
|
||||||
|
2. [test the binary](#workflow-for-testing-the-binary)
|
||||||
|
3. and if all goes well, [bump the version](#versioning-surplus-on-wheels-whatsapp-bridge)
|
||||||
|
and commit!
|
||||||
|
|
||||||
|
### workflow for building a binary
|
||||||
|
|
||||||
|
ensure you already have c compiler on the system (if you're using `nix develop` then yes you do), then run:
|
||||||
|
|
||||||
|
```text
|
||||||
|
CGO_ENABLED=1 go build
|
||||||
|
```
|
||||||
|
|
||||||
|
nix users can alternatively run:
|
||||||
|
|
||||||
|
```text
|
||||||
|
nix build .#native
|
||||||
|
```
|
||||||
|
|
||||||
|
instructions to build a Termux build are located at the
|
||||||
|
[bridges' documentation page](onwheels/whatsapp-bridge.md#anywhere-else), however nix users can run
|
||||||
|
the following instead for a reproducible, deterministic and hermetic build command:
|
||||||
|
|
||||||
|
```text
|
||||||
|
nix build .#termux
|
||||||
|
```
|
||||||
|
the resulting build will be in `result/spow-whatsapp-bridge`
|
||||||
|
|
||||||
|
### workflow for testing the binary
|
||||||
|
|
||||||
|
- test it out, making sure that you write dummy test text to `~/.cache/s+ow/message` before running
|
||||||
|
the binary
|
||||||
|
|
||||||
|
1. run `s+ow-whatsapp-bridge login` first
|
||||||
|
|
||||||
|
2. run `s+ow-whatsapp-bridge list` if you don't already have a chat ID
|
||||||
|
to send the test message to
|
||||||
|
|
||||||
|
3. run `s+ow-whatsapp-bridge` type or copy and paste in a `wa:`-prefixed chat ID
|
||||||
|
after it logs in, and verify it sends
|
||||||
|
|
||||||
|
if the bridge behaves nominally, [bump the version](#versioning-surplus-on-wheels-whatsapp-bridge)
|
||||||
|
and commit!
|
||||||
|
|
||||||
|
## workflow for versioning and tagging releases
|
||||||
|
|
||||||
|
### versioning surplus
|
||||||
|
|
||||||
|
format: `YEAR.MAJOR.MINOR[-PRERELEASE]` ([semantic versioning](https://semver.org/))
|
||||||
|
example: `2024.0.0`, `2024.0.0-beta`
|
||||||
|
change: update the `__version__` variable in `src/surplus/surplus.py`
|
||||||
|
|
||||||
|
### versioning surplus on wheels
|
||||||
|
|
||||||
|
i've tried to make surplus on wheels as reliable as it could be given a POSIX compliant shell and
|
||||||
|
commands you'd find available on virtually every linux system, Termux included
|
||||||
|
|
||||||
|
as such, it doesn't really follow a versioning scheme as it doesn't need to. also there's no
|
||||||
|
automatic updater for it, which would be overkill anyway
|
||||||
|
|
||||||
|
### versioning surplus on wheels: Telegram Bridge
|
||||||
|
|
||||||
|
format: `REVISION.YYYY.WW[+BUILD]` ([calendar versioning](https://calver.org/))
|
||||||
|
example: `2.2024.24`, `2.2024.24+1`
|
||||||
|
change: `version` key in `src/spow-telegram-bridge/pyproject.toml`
|
||||||
|
|
||||||
|
`REVISION` here meaning any general revision/change
|
||||||
|
|
||||||
|
the Telegram Bridge relies on [Telethon](https://github.com/LonamiWebs/Telethon/), which also
|
||||||
|
follows [semantic versioning](https://semver.org/). so, as long as major isn't bumped, or
|
||||||
|
as long as Telegram doesn't become Discord, the MTProto APIs to talk to Telegram should be
|
||||||
|
stable.
|
||||||
|
|
||||||
|
however because Telethon also relies on a bunch of networking libraries, it made some sense to
|
||||||
|
still do weekly builds to bump dependencies, getting pipx to download the newest compatible
|
||||||
|
dependencies as compared to dubiously running some sort of script to `pipx inject` dependencies
|
||||||
|
|
||||||
|
under normal circumstances, a non-working version of the bridge would and **should not have a
|
||||||
|
version bump**. but for any reason if an already tagged bridge is faulty and/or erroneous in
|
||||||
|
normal/expected usage, add a revision number to the end after a period (see example above)
|
||||||
|
|
||||||
|
### versioning surplus on wheels: WhatsApp Bridge
|
||||||
|
|
||||||
|
format: `REVISION.YYYY.WW[+BUILD]` ([calendar versioning](https://calver.org/))
|
||||||
|
example: `2.2024.25`, `2.2024.25+1`
|
||||||
|
change: `version` attribute of `bridge` attribute set in `src/spow-whatsapp-bridge/flake.nix`
|
||||||
|
|
||||||
|
`REVISION` here meaning any general revision/change
|
||||||
|
|
||||||
|
the WhatsApp Bridge relies on [whatsmeow](https://github.com/tulir/whatsmeow), a rolling release
|
||||||
|
library due to the volatile, undocumented nature of WhatsApp's multidevice API and also directly
|
||||||
|
and indirectly relies on a bunch of networking libraries:
|
||||||
|
|
||||||
|
``` title="src/spow-whatsapp-bridge/go.mod"
|
||||||
|
--8<-- "src/spow-whatsapp-bridge/go.mod"
|
||||||
|
```
|
||||||
|
|
||||||
|
as such, it uses a calendar versioning scheme and is built weekly
|
||||||
|
|
||||||
|
under normal circumstances, a non-working version of the bridge would and **should not have a
|
||||||
|
version bump**. but for any reason if an already tagged bridge is faulty and/or erroneous in
|
||||||
|
normal/expected usage, add a revision number to the end after a period (see example above)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## i've made my changes. what now?
|
||||||
|
|
||||||
|
if you're contributing back to surplus and/or the sibling projects, firstly, thanks!
|
||||||
|
see [the contributor's handbook](contributing.md) for what's next
|
||||||
BIN
docs/fonts/Geist-Regular.ttf
Normal file
BIN
docs/fonts/Geist-Regular.ttf
Normal file
Binary file not shown.
BIN
docs/fonts/GeistMono-Regular.ttf
Normal file
BIN
docs/fonts/GeistMono-Regular.ttf
Normal file
Binary file not shown.
BIN
docs/fonts/GeistMonoVF.woff2
Normal file
BIN
docs/fonts/GeistMonoVF.woff2
Normal file
Binary file not shown.
BIN
docs/fonts/GeistVF.woff2
Normal file
BIN
docs/fonts/GeistVF.woff2
Normal file
Binary file not shown.
92
docs/fonts/LICENSE.txt
Normal file
92
docs/fonts/LICENSE.txt
Normal file
|
|
@ -0,0 +1,92 @@
|
||||||
|
Copyright (c) 2023 Vercel, in collaboration with basement.studio
|
||||||
|
|
||||||
|
This Font Software is licensed under the SIL Open Font License, Version 1.1.
|
||||||
|
This license is copied below, and is also available with a FAQ at:
|
||||||
|
http://scripts.sil.org/OFL
|
||||||
|
|
||||||
|
-----------------------------------------------------------
|
||||||
|
SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
|
||||||
|
-----------------------------------------------------------
|
||||||
|
|
||||||
|
PREAMBLE
|
||||||
|
The goals of the Open Font License (OFL) are to stimulate worldwide
|
||||||
|
development of collaborative font projects, to support the font creation
|
||||||
|
efforts of academic and linguistic communities, and to provide a free and
|
||||||
|
open framework in which fonts may be shared and improved in partnership
|
||||||
|
with others.
|
||||||
|
|
||||||
|
The OFL allows the licensed fonts to be used, studied, modified and
|
||||||
|
redistributed freely as long as they are not sold by themselves. The
|
||||||
|
fonts, including any derivative works, can be bundled, embedded,
|
||||||
|
redistributed and/or sold with any software provided that any reserved
|
||||||
|
names are not used by derivative works. The fonts and derivatives,
|
||||||
|
however, cannot be released under any other type of license. The
|
||||||
|
requirement for fonts to remain under this license does not apply
|
||||||
|
to any document created using the fonts or their derivatives.
|
||||||
|
|
||||||
|
DEFINITIONS
|
||||||
|
"Font Software" refers to the set of files released by the Copyright
|
||||||
|
Holder(s) under this license and clearly marked as such. This may
|
||||||
|
include source files, build scripts and documentation.
|
||||||
|
|
||||||
|
"Reserved Font Name" refers to any names specified as such after the
|
||||||
|
copyright statement(s).
|
||||||
|
|
||||||
|
"Original Version" refers to the collection of Font Software components as
|
||||||
|
distributed by the Copyright Holder(s).
|
||||||
|
|
||||||
|
"Modified Version" refers to any derivative made by adding to, deleting,
|
||||||
|
or substituting -- in part or in whole -- any of the components of the
|
||||||
|
Original Version, by changing formats or by porting the Font Software to a
|
||||||
|
new environment.
|
||||||
|
|
||||||
|
"Author" refers to any designer, engineer, programmer, technical
|
||||||
|
writer or other person who contributed to the Font Software.
|
||||||
|
|
||||||
|
PERMISSION AND CONDITIONS
|
||||||
|
Permission is hereby granted, free of charge, to any person obtaining
|
||||||
|
a copy of the Font Software, to use, study, copy, merge, embed, modify,
|
||||||
|
redistribute, and sell modified and unmodified copies of the Font
|
||||||
|
Software, subject to the following conditions:
|
||||||
|
|
||||||
|
1) Neither the Font Software nor any of its individual components,
|
||||||
|
in Original or Modified Versions, may be sold by itself.
|
||||||
|
|
||||||
|
2) Original or Modified Versions of the Font Software may be bundled,
|
||||||
|
redistributed and/or sold with any software, provided that each copy
|
||||||
|
contains the above copyright notice and this license. These can be
|
||||||
|
included either as stand-alone text files, human-readable headers or
|
||||||
|
in the appropriate machine-readable metadata fields within text or
|
||||||
|
binary files as long as those fields can be easily viewed by the user.
|
||||||
|
|
||||||
|
3) No Modified Version of the Font Software may use the Reserved Font
|
||||||
|
Name(s) unless explicit written permission is granted by the corresponding
|
||||||
|
Copyright Holder. This restriction only applies to the primary font name as
|
||||||
|
presented to the users.
|
||||||
|
|
||||||
|
4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
|
||||||
|
Software shall not be used to promote, endorse or advertise any
|
||||||
|
Modified Version, except to acknowledge the contribution(s) of the
|
||||||
|
Copyright Holder(s) and the Author(s) or with their explicit written
|
||||||
|
permission.
|
||||||
|
|
||||||
|
5) The Font Software, modified or unmodified, in part or in whole,
|
||||||
|
must be distributed entirely under this license, and must not be
|
||||||
|
distributed under any other license. The requirement for fonts to
|
||||||
|
remain under this license does not apply to any document created
|
||||||
|
using the Font Software.
|
||||||
|
|
||||||
|
TERMINATION
|
||||||
|
This license becomes null and void if any of the above conditions are
|
||||||
|
not met.
|
||||||
|
|
||||||
|
DISCLAIMER
|
||||||
|
THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
|
||||||
|
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
|
||||||
|
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
|
||||||
|
OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
|
||||||
|
COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
|
||||||
|
INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
|
||||||
|
DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
|
||||||
|
FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
|
||||||
|
OTHER DEALINGS IN THE FONT SOFTWARE.
|
||||||
42
docs/index.md
Normal file
42
docs/index.md
Normal file
|
|
@ -0,0 +1,42 @@
|
||||||
|
# surplus (s+)
|
||||||
|
|
||||||
|
surplus (s+) is a Python script to convert [Google Maps Plus Codes](https://maps.google.com/pluscodes/)
|
||||||
|
to iOS Shortcuts-like shareable text
|
||||||
|
|
||||||
|
!!! tip
|
||||||
|
termux users can consider [surplus on wheels](onwheels/index.md), a sibling project that allows
|
||||||
|
you to run surplus regularly throughout the day and send it to someone on a messaging platform
|
||||||
|
|
||||||
|
!!! important
|
||||||
|
python 3.11 or later is required due to a bug in earlier versions
|
||||||
|
[(python/cpython#88089)](https://github.com/python/cpython/issues/88089)
|
||||||
|
|
||||||
|
install surplus with pip, or [pipx](https://pipx.pypa.io/) (recommended):
|
||||||
|
|
||||||
|
```text
|
||||||
|
pipx install surplus
|
||||||
|
```
|
||||||
|
|
||||||
|
then, use the `surplus` command, or its `s+` shorthand:
|
||||||
|
|
||||||
|
```text
|
||||||
|
$ s+ 7RGX+GJ Singapore
|
||||||
|
surplus version 2024.0.0
|
||||||
|
Singapore Conference Hall
|
||||||
|
7 Shenton Way
|
||||||
|
068809
|
||||||
|
Central, Singapore
|
||||||
|
```
|
||||||
|
|
||||||
|
the types of queries you can pass in are:
|
||||||
|
|
||||||
|
- full-length Plus Codes
|
||||||
|
`6PH58QMF+FX`
|
||||||
|
- shortened Plus Codes / 'local codes'
|
||||||
|
`8QMF+FX Singapore`
|
||||||
|
- latitude and longitude coordinate pairs
|
||||||
|
`1.3336875, 103.7749375`
|
||||||
|
- string queries
|
||||||
|
`Wisma Atria`
|
||||||
|
|
||||||
|
or, alternatively pass in `-` to read from stdin
|
||||||
113
docs/licences.md
Normal file
113
docs/licences.md
Normal file
|
|
@ -0,0 +1,113 @@
|
||||||
|
# licences
|
||||||
|
|
||||||
|
## [surplus](index.md)
|
||||||
|
|
||||||
|
**The Unlicence**
|
||||||
|
|
||||||
|
surplus is free and unencumbered software released into the public domain:
|
||||||
|
|
||||||
|
``` title="src/surplus/UNLICENCE"
|
||||||
|
--8<-- "src/surplus/UNLICENCE"
|
||||||
|
```
|
||||||
|
|
||||||
|
however, the dependencies surplus relies on are licenced under different, but still permissive
|
||||||
|
and open-source licences:
|
||||||
|
|
||||||
|
- [**geopy**](https://pypi.org/project/geopy/) —
|
||||||
|
Python Geocoding Toolbox
|
||||||
|
MIT Licence
|
||||||
|
|
||||||
|
- [**geographiclib**](https://pypi.org/project/geographiclib/) —
|
||||||
|
The geodesic routines from GeographicLib
|
||||||
|
MIT Licence
|
||||||
|
|
||||||
|
- [**pluscodes**](https://pypi.org/project/pluscodes/) —
|
||||||
|
Compute Plus Codes (Open Location Codes)
|
||||||
|
Apache 2.0
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## [surplus on wheels](onwheels/index.md)
|
||||||
|
|
||||||
|
**The Unlicence**
|
||||||
|
|
||||||
|
surplus on wheels is free and unencumbered software released into the public domain:
|
||||||
|
|
||||||
|
``` title="src/surplus-on-wheels/UNLICENCE"
|
||||||
|
--8<-- "src/surplus-on-wheels/UNLICENCE"
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## [surplus on wheels: WhatsApp Bridge](onwheels/whatsapp-bridge.md)
|
||||||
|
|
||||||
|
**Mozilla Public Licence 2.0**
|
||||||
|
|
||||||
|
the s+ow WhatsApp Bridge is based off of mdtest code from the
|
||||||
|
[whatsmeow](https://github.com/tulir/whatsmeow) project, which is licenced under the Mozilla
|
||||||
|
Public Licence 2.0:
|
||||||
|
|
||||||
|
``` title="src/spow-whatsapp-bridge/LICENCE"
|
||||||
|
--8<-- "src/spow-whatsapp-bridge/LICENCE"
|
||||||
|
```
|
||||||
|
|
||||||
|
the direct dependencies s+ow-whatsapp-bridge relies on are licenced under different, but still
|
||||||
|
permissive and open-source licences:
|
||||||
|
|
||||||
|
- [**whatsmeow**](https://github.com/tulir/whatsmeow) —
|
||||||
|
Go library for the WhatsApp web multidevice API
|
||||||
|
Mozilla Public Licence 2.0
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## [surplus on wheels: Telegram Bridge](onwheels/telegram-bridge.md)
|
||||||
|
|
||||||
|
**The Unlicence**
|
||||||
|
|
||||||
|
the s+ow Telegram Bridge is free and unencumbered software released into the public domain:
|
||||||
|
|
||||||
|
``` title="src/spow-telegram-bridge/UNLICENCE"
|
||||||
|
--8<-- "src/spow-telegram-bridge/UNLICENCE"
|
||||||
|
```
|
||||||
|
|
||||||
|
however, the direct dependencies surplus relies on are licenced under different, but still
|
||||||
|
permissive and open-source licences:
|
||||||
|
|
||||||
|
- [**Telethon**](https://pypi.org/project/Telethon/) —
|
||||||
|
Pure Python 3 MTProto API Telegram client library, for bots too!
|
||||||
|
MIT Licence
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## [surplus documentation](index.md)
|
||||||
|
|
||||||
|
**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 licence, visit <https://creativecommons.org/publicdomain/zero/1.0/>
|
||||||
|
|
||||||
|
``` title="docs/CC0"
|
||||||
|
--8<-- "docs/CC0"
|
||||||
|
```
|
||||||
|
|
||||||
|
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
|
||||||
|
|
||||||
|
``` title="docs/fonts/LICENSE.txt"
|
||||||
|
--8<-- "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
|
||||||
59
docs/links.md
Normal file
59
docs/links.md
Normal file
|
|
@ -0,0 +1,59 @@
|
||||||
|
# backup links
|
||||||
|
|
||||||
|
for when first-party links like <https://surplus.joshwel.co> and <https://forge.joshwel.co> are down:
|
||||||
|
|
||||||
|
## surplus
|
||||||
|
|
||||||
|
``` title="Primary Link"
|
||||||
|
https://forge.joshwel.co/mark/surplus.git
|
||||||
|
```
|
||||||
|
|
||||||
|
``` title="Alternative Link"
|
||||||
|
https://github.com/markjoshwel/surplus.git
|
||||||
|
```
|
||||||
|
|
||||||
|
## surplus on wheels
|
||||||
|
|
||||||
|
- shell script
|
||||||
|
|
||||||
|
``` title="Primary Link"
|
||||||
|
https://surplus.joshwel.co/spow.sh
|
||||||
|
```
|
||||||
|
|
||||||
|
``` title="Alternative Link"
|
||||||
|
https://raw.githubusercontent.com/markjoshwel/surplus/main/src/surplus-on-wheels/s+ow
|
||||||
|
```
|
||||||
|
|
||||||
|
- termux installation script
|
||||||
|
|
||||||
|
``` title="Primary Link"
|
||||||
|
https://surplus.joshwel.co/termux.sh
|
||||||
|
```
|
||||||
|
|
||||||
|
``` title="Alternative Link"
|
||||||
|
https://raw.githubusercontent.com/markjoshwel/surplus/main/src/surplus-on-wheels/install.sh
|
||||||
|
```
|
||||||
|
|
||||||
|
## surplus on wheels: Telegram Bridge
|
||||||
|
|
||||||
|
- install/update script:
|
||||||
|
|
||||||
|
``` title="Primary Link"
|
||||||
|
https://surplus.joshwel.co/telegram.sh
|
||||||
|
```
|
||||||
|
|
||||||
|
``` title="Alternative Link"
|
||||||
|
https://raw.githubusercontent.com/markjoshwel/surplus/main/src/spow-telegram-bridge/install.sh
|
||||||
|
```
|
||||||
|
|
||||||
|
## surplus on wheels: WhatsApp Bridge
|
||||||
|
|
||||||
|
- install/update script:
|
||||||
|
|
||||||
|
``` title="Primary Link"
|
||||||
|
https://surplus.joshwel.co/whatsapp.sh
|
||||||
|
```
|
||||||
|
|
||||||
|
``` title="Alternative Link"
|
||||||
|
https://raw.githubusercontent.com/markjoshwel/surplus/main/src/spow-whatsapp-bridge/install.sh
|
||||||
|
```
|
||||||
58
docs/onwheels/bridges.md
Normal file
58
docs/onwheels/bridges.md
Normal file
|
|
@ -0,0 +1,58 @@
|
||||||
|
# surplus on wheel bridges
|
||||||
|
|
||||||
|
## official bridges
|
||||||
|
|
||||||
|
there are two currently “official” bridges:
|
||||||
|
|
||||||
|
- [surplus on wheels: WhatsApp Bridge](whatsapp-bridge.md)
|
||||||
|
- [surplus on wheels: Telegram Bridge](telegram-bridge.md)
|
||||||
|
|
||||||
|
## bring your own bridge
|
||||||
|
|
||||||
|
### an informal specification
|
||||||
|
|
||||||
|
s+ow bridges are relatively simple as they are:
|
||||||
|
|
||||||
|
1. an executable or script
|
||||||
|
|
||||||
|
2. that reads in `SPOW_TARGETS` given by surplus to the bridge, using the standard input (stdin)
|
||||||
|
stream
|
||||||
|
|
||||||
|
1. bridges do not need to account for the possibility of multiple lines sent to stdin
|
||||||
|
|
||||||
|
2. bridges should account for the possibility of comma and space (`", "` instead of just `","`)
|
||||||
|
delimited targets, and strip each target of preceding and trailing whitespace
|
||||||
|
|
||||||
|
3. bridges should recognise a platform based on a prefix
|
||||||
|
(e.g. `wa:` for WhatsApp, `tg:` for Telegram, etc.)
|
||||||
|
|
||||||
|
3. reads `SPOW_MESSAGE` (`~/.cache/spow/message`) for the message content
|
||||||
|
|
||||||
|
notes:
|
||||||
|
|
||||||
|
1. stderr and stdout are redirected to s+ow’s error and output logs respectively unless the
|
||||||
|
`-p / --private` flag is passed to surplus
|
||||||
|
|
||||||
|
2. any errors encountered by the bridge should always result in a non-zero return. error logs will
|
||||||
|
show the exact error code, so feel free to use other numbers than 1
|
||||||
|
|
||||||
|
3. persistent data such as credentials and session data storage are to be handled by the
|
||||||
|
bridge itself. consider storing them in `$HOME/.local/share/<bridge-name>/`, or wherever
|
||||||
|
appropriate
|
||||||
|
|
||||||
|
### example
|
||||||
|
|
||||||
|
if i were to recommend an example on a basic bridge implementation, it would be the
|
||||||
|
[Telegram Bridge](telegram-bridge.md):
|
||||||
|
|
||||||
|
```python title="src/spow-telegram-bridge/bridge.py"
|
||||||
|
--8<-- "src/spow-telegram-bridge/bridge.py"
|
||||||
|
```
|
||||||
|
|
||||||
|
!!! note
|
||||||
|
the feature of deleting the last sent message (`--delete-last`) is a non-standard feature for
|
||||||
|
bridges, and was simply a use case i personally needed. if you're going to implement a bridge,
|
||||||
|
all you really need is the ability to `login`, `logout`, and [send a message](#an-informal-specification)
|
||||||
|
|
||||||
|
you can add other features as per the needs of your platform, like how the WhatsApp Bridge has
|
||||||
|
a `pair-phone` subcommand, or per your use case needs, like in the Telegram Bridge's `--delete-last`.
|
||||||
43
docs/onwheels/emulating-termux-location.md
Normal file
43
docs/onwheels/emulating-termux-location.md
Normal file
|
|
@ -0,0 +1,43 @@
|
||||||
|
# emulating `termux-location`
|
||||||
|
|
||||||
|
to bodge surplus on wheels (s+ow) on non-Termux systems
|
||||||
|
|
||||||
|
!!! note
|
||||||
|
dummy admonition for colour matching
|
||||||
|
|
||||||
|
!!! warning
|
||||||
|
dummy admonition for colour matching
|
||||||
|
|
||||||
|
`termux-location`, part of [Termux:API](https://wiki.termux.com/wiki/Termux:API), gets the device's
|
||||||
|
location via android apis and returns a json response through stdout:
|
||||||
|
|
||||||
|
```text
|
||||||
|
{
|
||||||
|
"latitude": 1.3277513,
|
||||||
|
"longitude": 103.678317,
|
||||||
|
"altitude": 51.6298828125,
|
||||||
|
"accuracy": 48.46337890625,
|
||||||
|
"vertical_accuracy": 38.4659423828125,
|
||||||
|
"bearing": 0.0,
|
||||||
|
"speed": 0.0,
|
||||||
|
"elapsedMs": 28,
|
||||||
|
"provider": "gps"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
see <https://wiki.termux.com/wiki/Termux-location> for more information
|
||||||
|
|
||||||
|
## implementing for surplus on wheels (s+ow)
|
||||||
|
|
||||||
|
s+ow will call the command a total of six times, being three pairs of parallel
|
||||||
|
`$LOCATION_CMD -p "network"` and `$LOCATION_CMD -p "gps"` invocations, before deciding after
|
||||||
|
exhausting all six runs on which output to choose, if any command runs were successful
|
||||||
|
|
||||||
|
even if somewhere in the termux-location implementation fails, it always (begrudgingly) returns
|
||||||
|
zero. s+ow will treat the invocation of the command as successful if there is **any output** to
|
||||||
|
the standard output (stdout) stream
|
||||||
|
|
||||||
|
## implementing for surplus (s+)
|
||||||
|
|
||||||
|
s+, when passed `--t / --using-termux-location`, will consume stdin, parse it as json and then
|
||||||
|
attempt to retrieve the `latitude` and `longitude` keys as floating point numbers
|
||||||
46
docs/onwheels/emulating-termux-notification.md
Normal file
46
docs/onwheels/emulating-termux-notification.md
Normal file
|
|
@ -0,0 +1,46 @@
|
||||||
|
# emulating `termux-notification`
|
||||||
|
|
||||||
|
to bodge surplus on wheels (s+ow) on non-Termux systems
|
||||||
|
|
||||||
|
`termux-notification`, part of [Termux:API](https://wiki.termux.com/wiki/Termux:API), sends out an
|
||||||
|
android notification
|
||||||
|
|
||||||
|
without `termux-notification`, s+ow will still run as it doesn't use `set -e` and very carefully
|
||||||
|
handles all command invocations, with `termux-notification` being the graceful exception\
|
||||||
|
|
||||||
|
however, if you would like to emulate it, make an executable globally reachable with the same name
|
||||||
|
|
||||||
|
s+ow uses the command as such:
|
||||||
|
|
||||||
|
```shell
|
||||||
|
termux-notification \
|
||||||
|
--priority "default" \
|
||||||
|
--title "surplus on wheels: No bridges" \
|
||||||
|
--content "No '$SPOW_BRIDGES' file; message is not sent."
|
||||||
|
```
|
||||||
|
|
||||||
|
```shell
|
||||||
|
termux-notification \
|
||||||
|
--priority "min" \
|
||||||
|
--ongoing \
|
||||||
|
--id "s+ow" \
|
||||||
|
--title "surplus on wheels" \
|
||||||
|
--content "s+ow has started running."
|
||||||
|
```
|
||||||
|
|
||||||
|
```shell
|
||||||
|
termux-notification \
|
||||||
|
--priority "min" \
|
||||||
|
--id "s+ow" \
|
||||||
|
--title "surplus on wheels" \
|
||||||
|
--content ...
|
||||||
|
```
|
||||||
|
|
||||||
|
```shell
|
||||||
|
termux-notification \
|
||||||
|
--priority "default" \
|
||||||
|
--title "surplus on wheels has errored" \
|
||||||
|
--content ...
|
||||||
|
```
|
||||||
|
|
||||||
|
see <https://wiki.termux.com/wiki/Termux-notification> for more information
|
||||||
329
docs/onwheels/index.md
Normal file
329
docs/onwheels/index.md
Normal file
|
|
@ -0,0 +1,329 @@
|
||||||
|
# surplus on wheels (s+ow)
|
||||||
|
|
||||||
|
surplus on wheels is a pure shell script to get your location using
|
||||||
|
[termux-location](https://wiki.termux.com/wiki/Termux-location), process it through surplus, and
|
||||||
|
send it to messaging service or wherever using “bridges”
|
||||||
|
|
||||||
|
surplus was made to emulate sending your location through the iOS Shortcuts app, and surplus on
|
||||||
|
wheels complements it by running surplus automatically using a cron job.
|
||||||
|
(but using it manually also works!)
|
||||||
|
|
||||||
|
## installing
|
||||||
|
|
||||||
|
!!! important
|
||||||
|
s+ow is a Termux-first script, and will not work anywhere else unless you have
|
||||||
|
a utility that emulates [termux-location](https://wiki.termux.com/wiki/termux-location)
|
||||||
|
on `$PATH` alongside bridges that supports your platform
|
||||||
|
|
||||||
|
there are two notable ways to install s+ow:
|
||||||
|
|
||||||
|
1. [as a standalone script](#as-a-standalone-script)
|
||||||
|
2. or, [as a cron job](#as-a-cron-job)
|
||||||
|
|
||||||
|
there is also an [installation script](#using-installation-scripts) for quickly getting
|
||||||
|
started from a _fresh_ termux installation
|
||||||
|
|
||||||
|
### as a standalone script
|
||||||
|
|
||||||
|
1. firstly install python and termux-api if you haven't already:
|
||||||
|
|
||||||
|
```text
|
||||||
|
pkg install python termux-api
|
||||||
|
```
|
||||||
|
|
||||||
|
also install the accompanying Termux:API app from [F-Froid](https://f-droid.org/en/packages/com.termux.api/)
|
||||||
|
|
||||||
|
2. install pipx if you haven't already:
|
||||||
|
|
||||||
|
```text
|
||||||
|
pip install pipx
|
||||||
|
```
|
||||||
|
|
||||||
|
3. install surplus:
|
||||||
|
|
||||||
|
```text
|
||||||
|
pipx install surplus
|
||||||
|
```
|
||||||
|
|
||||||
|
4. install surplus on wheels:
|
||||||
|
|
||||||
|
```text
|
||||||
|
mkdir -p ~/.local/bin/
|
||||||
|
wget -O ~/.local/bin/s+ow https://surplus.joshwel.co/spow.sh
|
||||||
|
chmod +x ~/.local/bin/s+ow
|
||||||
|
```
|
||||||
|
|
||||||
|
!!! note
|
||||||
|
if `wget` throws a 404, see [backup links](../links.md)
|
||||||
|
|
||||||
|
if `~/.local/bin` is not in your `$PATH`, add the following to your shell's rc file:
|
||||||
|
|
||||||
|
```shell
|
||||||
|
export PATH="$HOME/.local/bin:$PATH"
|
||||||
|
```
|
||||||
|
|
||||||
|
et voilà! s+ow is now setup. to actually send the message to a messaging platform,
|
||||||
|
[install an appropriate bridge](bridges.md)
|
||||||
|
|
||||||
|
### as a cron job
|
||||||
|
|
||||||
|
!!! important
|
||||||
|
these instructions rely on following the [previous instructions](#as-a-standalone-script)
|
||||||
|
|
||||||
|
1. install necessary packages to run cron jobs:
|
||||||
|
|
||||||
|
```text
|
||||||
|
pkg install cronie termux-services
|
||||||
|
```
|
||||||
|
|
||||||
|
2. restart termux and start the cron service:
|
||||||
|
|
||||||
|
```text
|
||||||
|
sv-enable cron
|
||||||
|
```
|
||||||
|
|
||||||
|
3. set up the cron job:
|
||||||
|
|
||||||
|
run the following command:
|
||||||
|
|
||||||
|
```text
|
||||||
|
crontab -e
|
||||||
|
```
|
||||||
|
|
||||||
|
and add the following text:
|
||||||
|
|
||||||
|
```text
|
||||||
|
59 * * * * bash -l -c "(SPOW_TARGETS="" SPOW_CRON=y s+ow)"
|
||||||
|
```
|
||||||
|
|
||||||
|
!!! important
|
||||||
|
minimally fill in the `SPOW_TARGETS` variable before running s+ow.
|
||||||
|
[(see usage for more info)](#usage)
|
||||||
|
|
||||||
|
this will run s+ow every hour, a minute before the hour
|
||||||
|
|
||||||
|
modify the variables as per your needs.
|
||||||
|
see [usage](#usage) for more information
|
||||||
|
|
||||||
|
et voilà! s+ow will now send a message every hour. feel free to experiment with the cron
|
||||||
|
job to your liking. see [crontab.guru](https://crontab.guru/) if you’re new to cron jobs
|
||||||
|
|
||||||
|
if you haven’t already, [install an appropriate bridge](bridges.md) to actually send a
|
||||||
|
message to a messaging platform
|
||||||
|
|
||||||
|
### using installation scripts
|
||||||
|
|
||||||
|
!!! warning
|
||||||
|
these scripts assume you're starting from a fresh base installation of Termux.
|
||||||
|
if you have already cron jobs, then manually carry out the instructions in
|
||||||
|
'[as a cron job](#as-a-cron-job)'
|
||||||
|
|
||||||
|
!!! important
|
||||||
|
if not installed already, install
|
||||||
|
[Termux:API from F-Droid](https://f-droid.org/en/packages/com.termux.api/), **not the Play Store**
|
||||||
|
|
||||||
|
1. setup s+ow:
|
||||||
|
|
||||||
|
```text
|
||||||
|
wget -O- https://surplus.joshwel.co/termux.sh | sh
|
||||||
|
```
|
||||||
|
|
||||||
|
!!! note
|
||||||
|
if `wget` throws a 404, see [backup links](../links.md)
|
||||||
|
|
||||||
|
2. restart termux!
|
||||||
|
|
||||||
|
3. and finally, [set up a cron job](#as-a-cron-job) from step 3 onwards ('set up the cron job')
|
||||||
|
|
||||||
|
## usage
|
||||||
|
|
||||||
|
### environment variables
|
||||||
|
|
||||||
|
s+ow's behaviour can be customised environment variables, with `SURPLUS_CMD` being the only
|
||||||
|
required variable:
|
||||||
|
|
||||||
|
1. `SPOW_TARGETS`
|
||||||
|
a single line of comma-delimited chat IDs with bridge prefixes
|
||||||
|
|
||||||
|
```text
|
||||||
|
wa:000000000000000000@g.us,tg:-0000000000000000000,...
|
||||||
|
```
|
||||||
|
|
||||||
|
in the example above, the WhatsApp chat ID is `wa:`-prefixed as recognised by the
|
||||||
|
[spow-whatsapp-bridge](whatsapp-bridge.md), and the
|
||||||
|
Telegram chat ID is `tg:`-prefixed as recognised by the
|
||||||
|
[spow-telegram-bridge](telegram-bridge.md)
|
||||||
|
|
||||||
|
2. `SPOW_CRON` (optional)
|
||||||
|
set as non-empty to declare that s+ow is being run as a cron job
|
||||||
|
|
||||||
|
if running as a cron job, start s+ow one minute earlier than intended to account for the time
|
||||||
|
it takes to run `termux-location` and `surplus`. s+ow assumes this and delays itself
|
||||||
|
appropriately
|
||||||
|
|
||||||
|
setting it to `n` will also be treated as if it were empty
|
||||||
|
|
||||||
|
3. `SPOW_PRIVATE` (optional)
|
||||||
|
set as non-empty to discard all logs when s+ow is done:
|
||||||
|
|
||||||
|
- `$HOME/.cache/s+ow/out.log` will be set to `/dev/null`
|
||||||
|
- `$HOME/.cache/s+ow/err.log` will be set to `/dev/null`
|
||||||
|
- `$HOME/.cache/s+ow/location.net.json` will be cleared after use locating the device
|
||||||
|
- `$HOME/.cache/s+ow/location.gps.json` will be cleared after use locating the device
|
||||||
|
- `$HOME/.cache/s+ow/location.json` will be cleared after use locating the device
|
||||||
|
- `$HOME/.cache/s+ow/surplus.out.log` will be cleared after use generating the message
|
||||||
|
- `$HOME/.cache/s+ow/surplus.err.log` will be set to `/dev/null`
|
||||||
|
- `$HOME/.cache/s+ow/message` will be cleared after all bridges has sent the message
|
||||||
|
|
||||||
|
!!! warning
|
||||||
|
the only file not cleared is s+ow's last successful message file, `$HOME/.cache/s+ow/last`,
|
||||||
|
as s+ow uses this as the first fallback message if it couldn't locate the device in time.
|
||||||
|
if you're fine with using the `LOCATION_FALLBACK` string, feel free to modify your
|
||||||
|
cron job to remove this file after running s+ow
|
||||||
|
|
||||||
|
setting it to `n` will also be treated as if it were empty
|
||||||
|
|
||||||
|
4. `SURPLUS_CMD` (optional)
|
||||||
|
the custom invocation used when calling surplus, modify this if you want to add certain flags
|
||||||
|
|
||||||
|
this defaults to `surplus -td`
|
||||||
|
|
||||||
|
!!! warning
|
||||||
|
when overriding, ensure you also have `-td` (`--using-termux-location` and `--debug`) in
|
||||||
|
your custom invocation!
|
||||||
|
|
||||||
|
5. `LOCATION_CMD` (optional)
|
||||||
|
the custom invocation used when calling `termux-location`, modify this if you want to bodge
|
||||||
|
together surplus on wheels on non-termux systems.
|
||||||
|
see ([emulating `termux-location`](emulating-termux-location.md)) for more information
|
||||||
|
|
||||||
|
this defaults to `termux-location`
|
||||||
|
|
||||||
|
6. `LOCATION_PRIORITISE_NETWORK` (optional)
|
||||||
|
set as non-empty to declare that s+ow can just use network location instead of GPS
|
||||||
|
if GPS is taking too long.
|
||||||
|
you should only turn this on if punctuality means that much to you, or you’re in a
|
||||||
|
country with cell towers close by or everywhere, like Singapore
|
||||||
|
|
||||||
|
the JIDs can be obtained by sending a message to the user/group, while running
|
||||||
|
`s+ow mdtest`, and examining the output for your message. JIDs are email address-like
|
||||||
|
strings
|
||||||
|
|
||||||
|
setting it to `n` will also be treated as if it were empty
|
||||||
|
|
||||||
|
7. `LOCATION_TIMEOUT` (optional)
|
||||||
|
set as a number to override the default first location timeout of `50`
|
||||||
|
|
||||||
|
8. `LOCATION_FALLBACK` (optional)
|
||||||
|
a string that can be formatted with three numbers using `%d`:
|
||||||
|
|
||||||
|
1. s+ow's status
|
||||||
|
2. number of location attempts before giving up
|
||||||
|
3. type of message sent
|
||||||
|
|
||||||
|
see [details on notification numbers](#details-on-notification-numbers) for the meanings of
|
||||||
|
each number. 'a', 'b' and 'c' map to `A`, `B` and `C`
|
||||||
|
|
||||||
|
defaults to `%d%d%d?`
|
||||||
|
|
||||||
|
### faking locations
|
||||||
|
|
||||||
|
> sometimes you gotta do what you gotta do
|
||||||
|
|
||||||
|
you can fake your s+ow messages by either:
|
||||||
|
|
||||||
|
1. setting a dummy `last` file in s+ow cache
|
||||||
|
|
||||||
|
`$HOME/.cache/s+ow/last` is used as the fallback response when a part of s+ow (either
|
||||||
|
`termux-location` or `surplus` errors out). you can set this file to whatever you want
|
||||||
|
and just turn off location on your device
|
||||||
|
|
||||||
|
2. setting a `fake` file in s+ow cache
|
||||||
|
|
||||||
|
!!! warning
|
||||||
|
s+ow uses the `read` command to read the file. as such, it is possible for s+ow to
|
||||||
|
prematurely stop reading the file if the file does not contain a trailing newline.
|
||||||
|
|
||||||
|
you can also write text to `$HOME/.cache/s+ow/fake` to fake upcoming messages. the file
|
||||||
|
is delimited by empty lines. as such, arrange the file like so:
|
||||||
|
|
||||||
|
```text
|
||||||
|
The Clementi Mall
|
||||||
|
3155 Commonwealth Avenue West
|
||||||
|
Westpeak Terrace
|
||||||
|
129588
|
||||||
|
Southwest, Singapore
|
||||||
|
|
||||||
|
Westgate
|
||||||
|
3 Gateway Drive
|
||||||
|
Jurong East
|
||||||
|
608532
|
||||||
|
Southwest, Singapore
|
||||||
|
|
||||||
|
...
|
||||||
|
|
||||||
|
```
|
||||||
|
|
||||||
|
on every run of s+ow, the first group of lines will be consumed, and the file will be
|
||||||
|
updated with the remaining lines. if the file is empty, it will be deleted
|
||||||
|
|
||||||
|
### details on notification numbers
|
||||||
|
|
||||||
|
after each run, or if s+ow had to use a location fallback string, s+ow notifies you:
|
||||||
|
|
||||||
|
!!! abstract "surplus on wheels"
|
||||||
|
Run has finished.
|
||||||
|
|
||||||
|
Singapore Conference Hall
|
||||||
|
7 Shenton Way
|
||||||
|
068809
|
||||||
|
Central, Singapore
|
||||||
|
|
||||||
|
(A, B, C, D<E>)
|
||||||
|
[lc:W sp:X sm:Y - Z]
|
||||||
|
|
||||||
|
!!! abstract "surplus on wheels has errored"
|
||||||
|
(A, B, C, D<E>)
|
||||||
|
[lc:W sp:X sm:Y - Z]
|
||||||
|
|
||||||
|
the top line denotes general statuses:
|
||||||
|
|
||||||
|
- `A`: s+ow's status
|
||||||
|
- `0` is nominal
|
||||||
|
- `1` is a termux-location error
|
||||||
|
- `2` is a surplus error
|
||||||
|
- `3` is a bridge/message send error
|
||||||
|
- `B`: number of location attempts before giving up
|
||||||
|
- `C`: type of message sent
|
||||||
|
- `0` for freshly made sharetext
|
||||||
|
- `1` for recycling a previous successful location sharetext (`last` file)
|
||||||
|
- `2` for using fallback template
|
||||||
|
- `D`: number of bridge failures
|
||||||
|
- `E`: each bridge's return code
|
||||||
|
|
||||||
|
the bottom line details on how long s+ow spent on each stage:
|
||||||
|
|
||||||
|
- `W`: time to locate
|
||||||
|
- `X`: time to run surplus
|
||||||
|
- `Y`: time to send message(s)
|
||||||
|
- `Z`: total run time
|
||||||
|
|
||||||
|
## help! a bridge isn't working!
|
||||||
|
|
||||||
|
cool. do the following:
|
||||||
|
|
||||||
|
1. log out and log back in and try again
|
||||||
|
|
||||||
|
2. if that didn't fix it, update/reinstall the bridge and try again
|
||||||
|
|
||||||
|
3. run the bridge's executable directly to see if there's any connection issues
|
||||||
|
look at your bridge's installation instructions to find out where it's located at.
|
||||||
|
or, use the `which` command
|
||||||
|
|
||||||
|
4. if it connected successfully, or you see no errors, try typing in one of the targets you've set
|
||||||
|
in `SPOW_TARGETS` for the bridge, and then press the enter/return key
|
||||||
|
|
||||||
|
!!! failure
|
||||||
|
on the off chance you reinstalled the bridge, and it still failed either step 3 or 4, the bridge
|
||||||
|
itself is faulty. file a bug report/issue with the bridge's project page or maintainer and tell
|
||||||
|
them where it failed (was it connecting to the messaging service? or failure to send a message?)
|
||||||
101
docs/onwheels/telegram-bridge.md
Normal file
101
docs/onwheels/telegram-bridge.md
Normal file
|
|
@ -0,0 +1,101 @@
|
||||||
|
# surplus on wheels: Telegram Bridge
|
||||||
|
|
||||||
|
Telegram Bridge for surplus on wheels (s+ow)
|
||||||
|
|
||||||
|
s+ow bridges are defined in a file named `$HOME/.s+ow-bridges`. each command in the file is run,
|
||||||
|
and comma-seperated target chat IDs are passed using stdin.
|
||||||
|
|
||||||
|
this bridge recognises targets prefixed with `tg:`.
|
||||||
|
|
||||||
|
```text
|
||||||
|
tg:<chat id>,...
|
||||||
|
```
|
||||||
|
|
||||||
|
## installation
|
||||||
|
|
||||||
|
!!! important
|
||||||
|
the following instructions implies that [surplus](../index.md) and [surplus on wheels](bridges.md)
|
||||||
|
have already been installed
|
||||||
|
|
||||||
|
1. install prerequisite software if not installed:
|
||||||
|
|
||||||
|
```text
|
||||||
|
pkg install git
|
||||||
|
```
|
||||||
|
|
||||||
|
```text
|
||||||
|
pip install pipx
|
||||||
|
```
|
||||||
|
|
||||||
|
2. install spow-telegram-bridge:
|
||||||
|
|
||||||
|
```text
|
||||||
|
wget -O- https://surplus.joshwel.co/telegram.sh | sh
|
||||||
|
```
|
||||||
|
|
||||||
|
!!! note
|
||||||
|
if `wget` throws a 404, see [backup links](../links.md)
|
||||||
|
|
||||||
|
3. add the following to your `$HOME/.s+ow-bridges` file:
|
||||||
|
|
||||||
|
```text
|
||||||
|
SPOW_TELEGRAM_API_HASH="" SPOW_TELEGRAM_API_ID="" s+ow-telegram-bridge
|
||||||
|
```
|
||||||
|
|
||||||
|
fill in SPOW_TELEGRAM_API_HASH and SPOW_TELEGRAM_API_ID accordingly.
|
||||||
|
see the [Telethon docs](https://docs.telethon.dev/en/stable/basic/signing-in.html) for
|
||||||
|
more information
|
||||||
|
|
||||||
|
to keep up to date, look at [updating](#updating) to set up a daily update cron job:
|
||||||
|
|
||||||
|
## updating
|
||||||
|
|
||||||
|
the installation script also sets up a shell script under the `s+ow-telegram-bridge-update` command
|
||||||
|
|
||||||
|
```text
|
||||||
|
s+ow-telegram-bridge-update
|
||||||
|
```
|
||||||
|
|
||||||
|
to do this automatically, make a cron job with `crontab -e`
|
||||||
|
and make a new line with the following text:
|
||||||
|
|
||||||
|
```text
|
||||||
|
0 0 * * * bash -l -c "s+ow-telegram-bridge-update"
|
||||||
|
```
|
||||||
|
|
||||||
|
this cron job will run the command every day at midnight
|
||||||
|
|
||||||
|
## usage
|
||||||
|
|
||||||
|
- `s+ow-telegram-bridge`
|
||||||
|
normal usage; sends latest message to tg:-prefixed targets given in stdin
|
||||||
|
|
||||||
|
- `s+ow-telegram-bridge login`
|
||||||
|
logs in to Telegram
|
||||||
|
|
||||||
|
- `s+ow-telegram-bridge logout`
|
||||||
|
logs out of Telegram
|
||||||
|
|
||||||
|
- `s+ow-telegram-bridge list`
|
||||||
|
lists all chats and their IDs
|
||||||
|
|
||||||
|
optional arguments:
|
||||||
|
|
||||||
|
- `--silent`
|
||||||
|
asks telegram to send message silently
|
||||||
|
- `--delete-last`
|
||||||
|
deletes last location message to prevent clutter
|
||||||
|
|
||||||
|
## versioning scheme
|
||||||
|
|
||||||
|
from `v2.2024.27`, the Telegram Bridge will automatically release a new version once a week if there
|
||||||
|
are updates to its dependencies
|
||||||
|
|
||||||
|
as such, the bridge is now versioned with a modified calendar versioning scheme of
|
||||||
|
`MAJOR.YEAR.ISOWEEK`, where the `MAJOR` version segment will be bumped with codebase changes, whereas
|
||||||
|
the `YEAR` and `ISOWEEK` segments will represent the time of which the release was built at
|
||||||
|
|
||||||
|
## licence
|
||||||
|
|
||||||
|
the s+ow Telegram Bridge is free and unencumbered software released into the public domain.
|
||||||
|
for more information, see [licences](../licences.md).
|
||||||
210
docs/onwheels/whatsapp-bridge.md
Normal file
210
docs/onwheels/whatsapp-bridge.md
Normal file
|
|
@ -0,0 +1,210 @@
|
||||||
|
# surplus on wheels: WhatsApp Bridge
|
||||||
|
|
||||||
|
WhatsApp Bridge for surplus on wheels (s+ow)
|
||||||
|
|
||||||
|
s+ow bridges are defined in a file named `$HOME/.s+ow-bridges`. each command in the file is run,
|
||||||
|
and comma-seperated target chat IDs are passed using stdin.
|
||||||
|
|
||||||
|
this bridge recognises targets prefixed with `wa:`.
|
||||||
|
|
||||||
|
```text
|
||||||
|
wa:<chat id>,...
|
||||||
|
```
|
||||||
|
|
||||||
|
## installation
|
||||||
|
|
||||||
|
### from a pre-built binary
|
||||||
|
|
||||||
|
```text
|
||||||
|
wget -O- https://surplus.joshwel.co/whatsapp.sh | sh
|
||||||
|
```
|
||||||
|
|
||||||
|
!!! note
|
||||||
|
if `wget` throws a 404, see [backup links](../links.md)
|
||||||
|
|
||||||
|
### building from source
|
||||||
|
|
||||||
|
#### on Termux
|
||||||
|
|
||||||
|
1. clone the repository at either `https://forge.joshwel.co/mark/surplus` or
|
||||||
|
`https://github.com/markjoshwel/surplus`, and navigate to `src/spow-whatsapp-bridge` within the
|
||||||
|
cloned repository
|
||||||
|
|
||||||
|
```text
|
||||||
|
git clone https://forge.joshwel.co/mark/surplus
|
||||||
|
cd surplus/src/spow-whatsapp-bridge
|
||||||
|
```
|
||||||
|
|
||||||
|
2. build the bridge:
|
||||||
|
|
||||||
|
```text
|
||||||
|
go build
|
||||||
|
```
|
||||||
|
|
||||||
|
for compatibility with the documentations' instructions as-is, rename the built binary to
|
||||||
|
`s+ow-whatsapp-bridge`
|
||||||
|
|
||||||
|
```text
|
||||||
|
mv spow-whatsapp-bridge s+ow-whatsapp-bridge
|
||||||
|
```
|
||||||
|
|
||||||
|
3. send the built binary over to your Termux environment, and then move it into the
|
||||||
|
`$HOME/.local/bin/` folder. if it doesn't exist, make it with `mkdir` and ensure that the folder
|
||||||
|
is in your `PATH` variable either using your `.profile`, `.bashrc` or whatever file is sourced
|
||||||
|
when opening your shell
|
||||||
|
|
||||||
|
#### anywhere else
|
||||||
|
|
||||||
|
for usage on Termux, see if the [Android NDK](https://developer.android.com/ndk/downloads) supports your platform
|
||||||
|
|
||||||
|
1. grab a copy of the NDK, and extract it somewhere. navigate to
|
||||||
|
`<ndk folder>/toolchains/llvm/prebuilt/<your platform>/bin` and look for a suitable `clang`
|
||||||
|
executable, as it will be your CGO compiler
|
||||||
|
|
||||||
|
```
|
||||||
|
m@csp:~/android-ndk-r26d/toolchains/llvm/prebuilt/linux-x86_64/bin$ ls *clang
|
||||||
|
aarch64-linux-android21-clang aarch64-linux-android30-clang ...
|
||||||
|
aarch64-linux-android22-clang aarch64-linux-android31-clang
|
||||||
|
aarch64-linux-android23-clang aarch64-linux-android32-clang
|
||||||
|
aarch64-linux-android24-clang aarch64-linux-android33-clang
|
||||||
|
aarch64-linux-android25-clang aarch64-linux-android34-clang
|
||||||
|
aarch64-linux-android26-clang armv7a-linux-androideabi21-clang
|
||||||
|
aarch64-linux-android27-clang armv7a-linux-androideabi22-clang
|
||||||
|
aarch64-linux-android28-clang armv7a-linux-androideabi23-clang
|
||||||
|
aarch64-linux-android29-clang armv7a-linux-androideabi24-clang
|
||||||
|
```
|
||||||
|
|
||||||
|
the example output is not exhaustive and is cut short for brevity and example, do take a look
|
||||||
|
at your downloaded NDK archive for what executables are available to you
|
||||||
|
|
||||||
|
many executables are present, so choose a) what architecture you will build for (more often
|
||||||
|
than not it's `aarch64`), and b) what target android api are you building for
|
||||||
|
|
||||||
|
if you're building for yourself, pick an api level/version that correlates to your devices'
|
||||||
|
android version. as an example, my device runs on an ARM processor (`aarch64`) and runs Android 14,
|
||||||
|
which is api level 34. (`android34`) as such, i would use the `aarch64-linux-android34-clang`
|
||||||
|
binary
|
||||||
|
|
||||||
|
2. clone the repository at either `https://forge.joshwel.co/mark/surplus` or
|
||||||
|
`https://github.com/markjoshwel/surplus`, and navigate to `src/spow-whatsapp-bridge` within the
|
||||||
|
cloned repository
|
||||||
|
|
||||||
|
```text
|
||||||
|
git clone https://forge.joshwel.co/mark/surplus
|
||||||
|
cd surplus/src/spow-whatsapp-bridge
|
||||||
|
```
|
||||||
|
|
||||||
|
3. build the bridge:
|
||||||
|
|
||||||
|
```text
|
||||||
|
CC="<path to android ndk clang executable>" GOOS=android GOARCH=arm64 CGO_ENABLED=1 go build
|
||||||
|
```
|
||||||
|
|
||||||
|
for compatibility with the documentations' instructions as-is, rename the built binary to
|
||||||
|
`s+ow-whatsapp-bridge`
|
||||||
|
|
||||||
|
```text
|
||||||
|
mv spow-whatsapp-bridge s+ow-whatsapp-bridge
|
||||||
|
```
|
||||||
|
|
||||||
|
4. send the built binary over to your Termux environment, and then move it into the
|
||||||
|
`$HOME/.local/bin/` folder. if it doesn't exist, make it with `mkdir` and ensure that the folder
|
||||||
|
is in your `PATH` variable either using your `.profile`, `.bashrc` or whatever file is sourced
|
||||||
|
when opening your shell
|
||||||
|
|
||||||
|
### post-installation setup
|
||||||
|
|
||||||
|
1. log into WhatsApp:
|
||||||
|
|
||||||
|
```text
|
||||||
|
s+ow-whatsapp-bridge login
|
||||||
|
```
|
||||||
|
|
||||||
|
give it a minute or two to sync your history. once the screen stops scrolling, you can safely
|
||||||
|
exit with Ctrl+D or Ctrl+C.
|
||||||
|
|
||||||
|
2. find out what chats you want the bridge to target:
|
||||||
|
|
||||||
|
```text
|
||||||
|
s+ow-whatsapp-bridge list
|
||||||
|
```
|
||||||
|
|
||||||
|
!!! note
|
||||||
|
for sending to individuals: their IDs are their internationalised phone numbers ending in
|
||||||
|
`@s.whatsapp.net`
|
||||||
|
|
||||||
|
example: `+65 9123 4567` is `6591234567@s.whatsapp.net`
|
||||||
|
|
||||||
|
then, note these down, prefixed with `wa:`, to them to your `SPOW_TARGETS` variable in your
|
||||||
|
s+ow cron job
|
||||||
|
|
||||||
|
3. finally, add the following to your $HOME/.s+ow-bridges file:
|
||||||
|
|
||||||
|
```text
|
||||||
|
s+ow-whatsapp-bridge
|
||||||
|
```
|
||||||
|
|
||||||
|
## updating
|
||||||
|
|
||||||
|
to keep updated as [whatsmeow](https://github.com/tulir/whatsmeow/), the library the bridge depends
|
||||||
|
on, has to keep updated with the WhatsApp web multidevice API, you can either:
|
||||||
|
|
||||||
|
1. [rebuild when a weekly release comes out](#building-from-source),
|
||||||
|
2. [or rely on the weekly continuous deployment builds](#from-a-pre-built-binary)
|
||||||
|
|
||||||
|
to use the weekly builds without building from scratch every time,
|
||||||
|
|
||||||
|
!!! note
|
||||||
|
this will pull the latest binary, around 20 megabytes in size, every day. if your network or
|
||||||
|
data plan may not take kindly to this, feel free to adjust the cron entry as you wish, or to
|
||||||
|
one that runs once a week instead:
|
||||||
|
|
||||||
|
```text
|
||||||
|
0 0 * * 0 bash -l -c "s+ow-whatsapp-bridge-update"
|
||||||
|
```
|
||||||
|
|
||||||
|
## usage
|
||||||
|
|
||||||
|
- `s+ow-whatsapp-bridge`
|
||||||
|
normal usage; sends latest message to wa:-prefixed targets given in stdin
|
||||||
|
|
||||||
|
- `s+ow-whatsapp-bridge login`
|
||||||
|
logs in to WhatsApp
|
||||||
|
|
||||||
|
- `s+ow-whatsapp-bridge pair-phone`
|
||||||
|
logs in to WhatsApp using a phone number
|
||||||
|
|
||||||
|
- `s+ow-whatsapp-bridge reconnect`
|
||||||
|
reconnects the client
|
||||||
|
|
||||||
|
- `s+ow-whatsapp-bridge logout`
|
||||||
|
logs out of WhatsApp
|
||||||
|
|
||||||
|
- `s+ow-whatsapp-bridge list`
|
||||||
|
lists all group chats and their IDs.
|
||||||
|
|
||||||
|
for sending to individuals: their IDs are their internationalised phone numbers ending in
|
||||||
|
`@s.whatsapp.net`
|
||||||
|
|
||||||
|
example: `+65 9123 4567` is `6591234567@s.whatsapp.net`
|
||||||
|
|
||||||
|
## verifying a pre-built binary
|
||||||
|
|
||||||
|
!!! note
|
||||||
|
if you installed the bridge through an installation script, it would have already
|
||||||
|
|
||||||
|
and if the script or `s+ow-whatsapp-bridge-update` throws an error about failing verification,
|
||||||
|
you can use the environment variable ``
|
||||||
|
|
||||||
|
TODO
|
||||||
|
|
||||||
|
## versioning scheme
|
||||||
|
|
||||||
|
from `v2.2024.25`, the bridge is now versioned with a modified calendar versioning scheme of
|
||||||
|
`MAJOR.YEAR.ISOWEEK`, where the `MAJOR` version segment will be bumped with codebase changes, whereas
|
||||||
|
the `YEAR` and `ISOWEEK` segments will represent the time of which the release was built at
|
||||||
|
|
||||||
|
## licence
|
||||||
|
|
||||||
|
the s+ow Telegram Bridge is free and unencumbered software released into the public domain.
|
||||||
|
for more information, see [licences](../licences.md).
|
||||||
212
docs/stylesheets/extra.css
Normal file
212
docs/stylesheets/extra.css
Normal file
|
|
@ -0,0 +1,212 @@
|
||||||
|
@font-face {
|
||||||
|
font-family: "Geist";
|
||||||
|
src: url('../fonts/GeistVF.woff2') format('woff2'),
|
||||||
|
url('../fonts/Geist-Regular.ttf') format('truetype');
|
||||||
|
}
|
||||||
|
@font-face {
|
||||||
|
font-family: "Geist Mono";
|
||||||
|
src: url('../fonts/GeistMonoVF.woff2') format('woff2'),
|
||||||
|
url('../fonts/GeistMono-Regular.ttf') format('truetype');
|
||||||
|
}
|
||||||
|
|
||||||
|
:root {
|
||||||
|
--md-text-font: "Geist";
|
||||||
|
--md-code-font: "Geist Mono";
|
||||||
|
--md-hue: 180deg;
|
||||||
|
}
|
||||||
|
|
||||||
|
* {
|
||||||
|
text-rendering: geometricprecision !important;
|
||||||
|
-webkit-font-smoothing: antialiased;
|
||||||
|
}
|
||||||
|
|
||||||
|
[data-md-color-scheme="default"] {
|
||||||
|
color-scheme: light;
|
||||||
|
|
||||||
|
--md-sys-color-primary: rgb(51 71 65);
|
||||||
|
--md-sys-color-surface-tint: rgb(78 99 92);
|
||||||
|
--md-sys-color-on-primary: rgb(255 255 255);
|
||||||
|
--md-sys-color-primary-container: rgb(95 116 109);
|
||||||
|
--md-sys-color-on-primary-container: rgb(255 255 255);
|
||||||
|
--md-sys-color-secondary: rgb(61 69 66);
|
||||||
|
--md-sys-color-on-secondary: rgb(255 255 255);
|
||||||
|
--md-sys-color-secondary-container: rgb(110 118 115);
|
||||||
|
--md-sys-color-on-secondary-container: rgb(255 255 255);
|
||||||
|
--md-sys-color-tertiary: rgb(0 73 93);
|
||||||
|
--md-sys-color-on-tertiary: rgb(255 255 255);
|
||||||
|
--md-sys-color-tertiary-container: rgb(65 124 147);
|
||||||
|
--md-sys-color-on-tertiary-container: rgb(255 255 255);
|
||||||
|
--md-sys-color-error: rgb(124 37 0);
|
||||||
|
--md-sys-color-on-error: rgb(255 255 255);
|
||||||
|
--md-sys-color-error-container: rgb(200 77 28);
|
||||||
|
--md-sys-color-on-error-container: rgb(255 255 255);
|
||||||
|
--md-sys-color-background: rgb(251 249 247);
|
||||||
|
--md-sys-color-on-background: rgb(27 28 27);
|
||||||
|
--md-sys-color-surface: rgb(251 249 247);
|
||||||
|
--md-sys-color-on-surface: rgb(27 28 27);
|
||||||
|
--md-sys-color-surface-variant: rgb(222 228 224);
|
||||||
|
--md-sys-color-on-surface-variant: rgb(62 68 66);
|
||||||
|
--md-sys-color-outline: rgb(90 96 94);
|
||||||
|
--md-sys-color-outline-variant: rgb(118 124 121);
|
||||||
|
--md-sys-color-shadow: rgb(0 0 0);
|
||||||
|
--md-sys-color-scrim: rgb(0 0 0);
|
||||||
|
--md-sys-color-inverse-surface: rgb(48 49 48);
|
||||||
|
--md-sys-color-inverse-on-surface: rgb(242 240 239);
|
||||||
|
--md-sys-color-inverse-primary: rgb(181 203 195);
|
||||||
|
--md-sys-color-primary-fixed: rgb(100 121 114);
|
||||||
|
--md-sys-color-on-primary-fixed: rgb(255 255 255);
|
||||||
|
--md-sys-color-primary-fixed-dim: rgb(76 96 90);
|
||||||
|
--md-sys-color-on-primary-fixed-variant: rgb(255 255 255);
|
||||||
|
--md-sys-color-secondary-fixed: rgb(110 118 115);
|
||||||
|
--md-sys-color-on-secondary-fixed: rgb(255 255 255);
|
||||||
|
--md-sys-color-secondary-fixed-dim: rgb(86 94 90);
|
||||||
|
--md-sys-color-on-secondary-fixed-variant: rgb(255 255 255);
|
||||||
|
--md-sys-color-tertiary-fixed: rgb(65 124 147);
|
||||||
|
--md-sys-color-on-tertiary-fixed: rgb(255 255 255);
|
||||||
|
--md-sys-color-tertiary-fixed-dim: rgb(36 99 121);
|
||||||
|
--md-sys-color-on-tertiary-fixed-variant: rgb(255 255 255);
|
||||||
|
--md-sys-color-surface-dim: rgb(219 218 216);
|
||||||
|
--md-sys-color-surface-bright: rgb(251 249 247);
|
||||||
|
--md-sys-color-surface-container-lowest: rgb(255 255 255);
|
||||||
|
--md-sys-color-surface-container-low: rgb(245 243 242);
|
||||||
|
--md-sys-color-surface-container: rgb(239 238 236);
|
||||||
|
--md-sys-color-surface-container-high: rgb(233 232 230);
|
||||||
|
--md-sys-color-surface-container-highest: rgb(228 226 225);
|
||||||
|
|
||||||
|
--md-hue: 139.2deg;
|
||||||
|
--md-default-fg-color: var(--md-sys-color-primary);
|
||||||
|
--md-default-bg-color: var(--md-sys-color-surface);
|
||||||
|
|
||||||
|
/* primary colours */
|
||||||
|
--md-primary-fg-color: var(--md-sys-color-primary);
|
||||||
|
--md-primary-fg-color--light: var(--md-sys-color-inverse-primary);
|
||||||
|
--md-primary-fg-color--dark: var(--md-sys-color-primary-container);
|
||||||
|
--md-primary-bg-color: var(--md-sys-color-surface);
|
||||||
|
--md-primary-bg-color--light: var(--md-sys-color-surface-dim);
|
||||||
|
|
||||||
|
/* accent (interactable) colours */
|
||||||
|
--md-accent-fg-color: var(--md-sys-color-tertiary);
|
||||||
|
--md-accent-bg-color: var(--md-sys-color-on-tertiary);
|
||||||
|
--md-accent-bg-color--light: var(--md-sys-color-surface-dim);
|
||||||
|
|
||||||
|
/* typesetting colours */
|
||||||
|
--md-typeset-color: var(--md-sys-color-on-surface);
|
||||||
|
--md-typeset-a-color: var(--md-sys-color-tertiary);
|
||||||
|
--md-typeset-del-color: var(--md-sys-color-on-error-container);
|
||||||
|
--md-typeset-ins-color: var(--md-sys-color-on-primary-container);
|
||||||
|
--md-typeset-kbd-color: var(--md-sys-color-surface-container-lowest);
|
||||||
|
--md-typeset-kbd-accent-color: var(--md-sys-color-surface-container);
|
||||||
|
--md-typeset-kbd-border-color: var(--md-sys-color-surface-container-highest);
|
||||||
|
--md-typeset-mark-color: var(--md-sys-color-tertiary-container);
|
||||||
|
--md-typeset-table-color: var(--md-sys-color-outline);
|
||||||
|
--md-code-bg-color: var(--md-sys-color-surface-container-high);
|
||||||
|
|
||||||
|
/* admonition colours */
|
||||||
|
--md-admonition-fg-color: var(--md-sys-color-secondary);
|
||||||
|
--md-admonition-bg-color: var(--md-default-bg-color);
|
||||||
|
--md-warning-fg-color: var(--md-sys-color-on-error-container);
|
||||||
|
--md-warning-bg-color: var(--md-sys-color-error-container);
|
||||||
|
|
||||||
|
/* footer colours */
|
||||||
|
--md-footer-fg-color: var(--md-sys-color-on-surface);
|
||||||
|
--md-footer-fg-color--light: var(--md-sys-color-on-surface-variant);
|
||||||
|
--md-footer-fg-color--lighter: var(--md-sys-color-outline);
|
||||||
|
--md-footer-bg-color: var(--md-sys-color-surface-dim);
|
||||||
|
--md-footer-bg-color--dark: var(--md-sys-color-surface-container-highest);
|
||||||
|
}
|
||||||
|
|
||||||
|
[data-md-color-scheme="slate"] {
|
||||||
|
color-scheme: dark;
|
||||||
|
|
||||||
|
--md-sys-color-primary: rgb(185 208 199);
|
||||||
|
--md-sys-color-surface-tint: rgb(181 203 195);
|
||||||
|
--md-sys-color-on-primary: rgb(6 26 21);
|
||||||
|
--md-sys-color-primary-container: rgb(128 149 142);
|
||||||
|
--md-sys-color-on-primary-container: rgb(0 0 0);
|
||||||
|
--md-sys-color-secondary: rgb(196 205 200);
|
||||||
|
--md-sys-color-on-secondary: rgb(16 24 21);
|
||||||
|
--md-sys-color-secondary-container: rgb(138 147 143);
|
||||||
|
--md-sys-color-on-secondary-container: rgb(0 0 0);
|
||||||
|
--md-sys-color-tertiary: rgb(153 211 236);
|
||||||
|
--md-sys-color-on-tertiary: rgb(0 25 34);
|
||||||
|
--md-sys-color-tertiary-container: rgb(99 157 181);
|
||||||
|
--md-sys-color-on-tertiary-container: rgb(0 0 0);
|
||||||
|
--md-sys-color-error: rgb(255 187 164);
|
||||||
|
--md-sys-color-on-error: rgb(48 9 0);
|
||||||
|
--md-sys-color-error-container: rgb(237 104 54);
|
||||||
|
--md-sys-color-on-error-container: rgb(0 0 0);
|
||||||
|
--md-sys-color-background: rgb(19 20 19);
|
||||||
|
--md-sys-color-on-background: rgb(228 226 225);
|
||||||
|
--md-sys-color-surface: rgb(19 20 19);
|
||||||
|
--md-sys-color-on-surface: rgb(252 250 249);
|
||||||
|
--md-sys-color-surface-variant: rgb(66 72 70);
|
||||||
|
--md-sys-color-on-surface-variant: rgb(198 204 200);
|
||||||
|
--md-sys-color-outline: rgb(158 164 161);
|
||||||
|
--md-sys-color-outline-variant: rgb(126 132 129);
|
||||||
|
--md-sys-color-shadow: rgb(0 0 0);
|
||||||
|
--md-sys-color-scrim: rgb(0 0 0);
|
||||||
|
--md-sys-color-inverse-surface: rgb(228 226 225);
|
||||||
|
--md-sys-color-inverse-on-surface: rgb(41 42 41);
|
||||||
|
--md-sys-color-inverse-primary: rgb(56 76 70);
|
||||||
|
--md-sys-color-primary-fixed: rgb(209 232 223);
|
||||||
|
--md-sys-color-on-primary-fixed: rgb(2 20 16);
|
||||||
|
--md-sys-color-primary-fixed-dim: rgb(181 203 195);
|
||||||
|
--md-sys-color-on-primary-fixed-variant: rgb(38 58 52);
|
||||||
|
--md-sys-color-secondary-fixed: rgb(220 228 224);
|
||||||
|
--md-sys-color-on-secondary-fixed: rgb(11 19 16);
|
||||||
|
--md-sys-color-secondary-fixed-dim: rgb(192 200 196);
|
||||||
|
--md-sys-color-on-secondary-fixed-variant: rgb(48 56 53);
|
||||||
|
--md-sys-color-tertiary-fixed: rgb(186 234 255);
|
||||||
|
--md-sys-color-on-tertiary-fixed: rgb(0 20 27);
|
||||||
|
--md-sys-color-tertiary-fixed-dim: rgb(149 207 232);
|
||||||
|
--md-sys-color-on-tertiary-fixed-variant: rgb(0 59 76);
|
||||||
|
--md-sys-color-surface-dim: rgb(19 20 19);
|
||||||
|
--md-sys-color-surface-bright: rgb(57 57 56);
|
||||||
|
--md-sys-color-surface-container-lowest: rgb(13 14 14);
|
||||||
|
--md-sys-color-surface-container-low: rgb(27 28 27);
|
||||||
|
--md-sys-color-surface-container: rgb(31 32 31);
|
||||||
|
--md-sys-color-surface-container-high: rgb(41 42 41);
|
||||||
|
--md-sys-color-surface-container-highest: rgb(52 53 52);
|
||||||
|
|
||||||
|
/*--md-hue: 139.2deg;*/
|
||||||
|
--md-default-fg-color: var(--md-sys-color-primary);
|
||||||
|
--md-default-bg-color: var(--md-sys-color-surface);
|
||||||
|
|
||||||
|
/* primary colours */
|
||||||
|
--md-primary-fg-color: var(--md-sys-color-primary);
|
||||||
|
--md-primary-fg-color--light: var(--md-sys-color-inverse-primary);
|
||||||
|
--md-primary-fg-color--dark: var(--md-sys-color-primary-container);
|
||||||
|
--md-primary-bg-color: var(--md-sys-color-surface);
|
||||||
|
--md-primary-bg-color--light: var(--md-sys-color-surface-dim);
|
||||||
|
|
||||||
|
/* accent (interactable) colours */
|
||||||
|
--md-accent-fg-color: var(--md-sys-color-tertiary);
|
||||||
|
--md-accent-bg-color: var(--md-sys-color-on-tertiary);
|
||||||
|
--md-accent-bg-color--light: var(--md-sys-color-surface-dim);
|
||||||
|
|
||||||
|
/* typesetting colours */
|
||||||
|
--md-typeset-color: var(--md-sys-color-on-surface);
|
||||||
|
--md-typeset-a-color: var(--md-sys-color-tertiary);
|
||||||
|
--md-typeset-del-color: var(--md-sys-color-on-error-container);
|
||||||
|
--md-typeset-ins-color: var(--md-sys-color-on-primary-container);
|
||||||
|
--md-typeset-kbd-color: var(--md-sys-color-surface-container-lowest);
|
||||||
|
--md-typeset-kbd-accent-color: var(--md-sys-color-surface-container);
|
||||||
|
--md-typeset-kbd-border-color: var(--md-sys-color-surface-container-highest);
|
||||||
|
--md-typeset-mark-color: var(--md-sys-color-tertiary-container);
|
||||||
|
--md-typeset-table-color: var(--md-sys-color-outline);
|
||||||
|
--md-typeset-table-color--light: var(--md-sys-color-outline-variant);
|
||||||
|
--md-code-bg-color: var(--md-sys-color-surface-container-high);
|
||||||
|
|
||||||
|
/* admonition colours */
|
||||||
|
--md-admonition-fg-color: var(--md-sys-color-secondary);
|
||||||
|
--md-admonition-bg-color: var(--md-default-bg-color);
|
||||||
|
--md-warning-fg-color: var(--md-sys-color-on-error-container);
|
||||||
|
--md-warning-bg-color: var(--md-sys-color-error-container);
|
||||||
|
|
||||||
|
/* footer colours */
|
||||||
|
--md-footer-fg-color: var(--md-sys-color-on-surface);
|
||||||
|
--md-footer-fg-color--light: var(--md-sys-color-on-surface-variant);
|
||||||
|
--md-footer-fg-color--lighter: var(--md-sys-color-outline);
|
||||||
|
--md-footer-bg-color: var(--md-sys-color-surface-dim);
|
||||||
|
--md-footer-bg-color--dark: var(--md-sys-color-surface-container-highest);
|
||||||
|
}
|
||||||
4
docs/stylesheets/pdf.scss
Normal file
4
docs/stylesheets/pdf.scss
Normal file
|
|
@ -0,0 +1,4 @@
|
||||||
|
@page {
|
||||||
|
size: A4;
|
||||||
|
margin: 1.25cm;
|
||||||
|
}
|
||||||
11
docs/using.md
Normal file
11
docs/using.md
Normal file
|
|
@ -0,0 +1,11 @@
|
||||||
|
# the user's handbook
|
||||||
|
|
||||||
|
TODO
|
||||||
|
|
||||||
|
## as a command line tool
|
||||||
|
|
||||||
|
TODO
|
||||||
|
|
||||||
|
## as a python library
|
||||||
|
|
||||||
|
TODO
|
||||||
114
mkdocs.yml
Normal file
114
mkdocs.yml
Normal file
|
|
@ -0,0 +1,114 @@
|
||||||
|
site_name: surplus Documentation
|
||||||
|
site_url: https://surplus.joshwel.co
|
||||||
|
site_author: Mark Joshwel and surplus contributors
|
||||||
|
site_description: documentation for the surplus and sibling projects
|
||||||
|
|
||||||
|
repo_name: markjoshwel/surplus
|
||||||
|
repo_url: https://github.com/markjoshwel/surplus
|
||||||
|
|
||||||
|
copyright: |
|
||||||
|
with with all our hearts, 2023-2024, mark joshwel and contributors<br>
|
||||||
|
documentation is dedicated to the public domain with <a href="https://creativecommons.org/publicdomain/zero/1.0/">CC0</a>
|
||||||
|
|
||||||
|
nav:
|
||||||
|
- about:
|
||||||
|
- surplus: "index.md"
|
||||||
|
- licences: "licences.md"
|
||||||
|
- changelog: "changelog.md"
|
||||||
|
- handbooks:
|
||||||
|
- "using.md"
|
||||||
|
- "developing.md"
|
||||||
|
- "contributing.md"
|
||||||
|
- on wheels:
|
||||||
|
- "onwheels/index.md"
|
||||||
|
- bridges:
|
||||||
|
- about bridges: "onwheels/bridges.md"
|
||||||
|
- "onwheels/telegram-bridge.md"
|
||||||
|
- "onwheels/whatsapp-bridge.md"
|
||||||
|
- "onwheels/emulating-termux-location.md"
|
||||||
|
- "onwheels/emulating-termux-notification.md"
|
||||||
|
- backup links:
|
||||||
|
"links.md"
|
||||||
|
|
||||||
|
theme:
|
||||||
|
name: material
|
||||||
|
language: en
|
||||||
|
|
||||||
|
features:
|
||||||
|
- navigation.tabs
|
||||||
|
- navigation.tabs.sticky
|
||||||
|
- navigation.tracking
|
||||||
|
- navigation.expand
|
||||||
|
- toc.integrate
|
||||||
|
- search.suggest
|
||||||
|
- search.highlight
|
||||||
|
- content.tabs.link
|
||||||
|
- content.code.annotation
|
||||||
|
- content.code.copy
|
||||||
|
- pymdownx.snippets
|
||||||
|
|
||||||
|
font: false
|
||||||
|
|
||||||
|
palette:
|
||||||
|
- media: "(prefers-color-scheme)"
|
||||||
|
toggle:
|
||||||
|
icon: material/brightness-auto
|
||||||
|
name: Light Theme
|
||||||
|
primary: custom
|
||||||
|
accent: custom
|
||||||
|
- media: "(prefers-color-scheme: light)"
|
||||||
|
scheme: default
|
||||||
|
toggle:
|
||||||
|
icon: material/brightness-7
|
||||||
|
name: Dark Theme
|
||||||
|
primary: custom
|
||||||
|
accent: custom
|
||||||
|
- media: "(prefers-color-scheme: dark)"
|
||||||
|
scheme: slate
|
||||||
|
toggle:
|
||||||
|
icon: material/brightness-4
|
||||||
|
name: System Theme
|
||||||
|
primary: custom
|
||||||
|
accent: custom
|
||||||
|
|
||||||
|
icon:
|
||||||
|
admonition:
|
||||||
|
abstract: material/text-box-outline
|
||||||
|
tip: material/pencil-outline
|
||||||
|
note: material/information-slab-box-outline
|
||||||
|
warning: material/alert-outline
|
||||||
|
danger: material/alert-octagon-outline
|
||||||
|
|
||||||
|
|
||||||
|
extra_css:
|
||||||
|
- stylesheets/extra.css
|
||||||
|
|
||||||
|
plugins:
|
||||||
|
- search
|
||||||
|
- privacy
|
||||||
|
#- git-revision-date-localized:
|
||||||
|
# enable_creation_date: true
|
||||||
|
- exporter:
|
||||||
|
formats:
|
||||||
|
pdf:
|
||||||
|
enabled: !ENV [MKDOCS_EXPORTER_PDF_ENABLED, true]
|
||||||
|
stylesheets:
|
||||||
|
- docs/stylesheets/pdf.scss
|
||||||
|
aggregator:
|
||||||
|
enabled: true
|
||||||
|
output: documentation.pdf
|
||||||
|
buttons:
|
||||||
|
- title: Download as PDF
|
||||||
|
icon: material-file-download-outline
|
||||||
|
enabled: !!python/name:mkdocs_exporter.formats.pdf.buttons.download.enabled
|
||||||
|
attributes: !!python/name:mkdocs_exporter.formats.pdf.buttons.download.attributes
|
||||||
|
|
||||||
|
markdown_extensions:
|
||||||
|
- admonition
|
||||||
|
- pymdownx.highlight:
|
||||||
|
anchor_linenums: true
|
||||||
|
line_spans: __span
|
||||||
|
pygments_lang_class: true
|
||||||
|
- pymdownx.inlinehilite
|
||||||
|
- pymdownx.snippets
|
||||||
|
- pymdownx.superfences
|
||||||
23
src/tools/docs-prebuild.py
Normal file
23
src/tools/docs-prebuild.py
Normal file
|
|
@ -0,0 +1,23 @@
|
||||||
|
"""
|
||||||
|
script to copy shell scripts into the docs folder for publishing
|
||||||
|
|
||||||
|
src/surplus-on-wheels/s+ow -> docs/spow.sh
|
||||||
|
src/surplus-on-wheels/termux-s+ow-setup -> docs/termux.sh
|
||||||
|
src/spow-whatsapp-bridge/install.sh -> docs/whatsapp.sh
|
||||||
|
src/spow-telegram-bridge/install.sh -> docs/telegram.sh
|
||||||
|
"""
|
||||||
|
from pathlib import Path
|
||||||
|
from shutil import copyfile
|
||||||
|
|
||||||
|
repo_root: Path = Path(__file__).parent.parent.parent
|
||||||
|
docs_path: Path = repo_root.joinpath("docs")
|
||||||
|
|
||||||
|
copy_map: dict[Path, Path] = {
|
||||||
|
repo_root.joinpath("src/surplus-on-wheels/s+ow"): docs_path.joinpath("spow.sh"),
|
||||||
|
repo_root.joinpath("src/surplus-on-wheels/install.sh"): docs_path.joinpath("termux.sh"),
|
||||||
|
repo_root.joinpath("src/spow-whatsapp-bridge/install.sh"): docs_path.joinpath("whatsapp.sh"),
|
||||||
|
repo_root.joinpath("src/spow-telegram-bridge/install.sh"): docs_path.joinpath("telegram.sh"),
|
||||||
|
}
|
||||||
|
|
||||||
|
for target, destination in copy_map.items():
|
||||||
|
copyfile(target, destination)
|
||||||
Loading…
Reference in a new issue