docs: many (#1)

- fix/update table of contents
- add api reference
- add wrong format contrib guide
- update usage and examples
This commit is contained in:
Mark Joshwel 2023-06-03 08:31:02 +00:00
parent cb147407b7
commit a61a80d8c1

159
README.md
View file

@ -1,10 +1,18 @@
# surplus
plus code to iOS-Shortcuts-like shareable text
Plus Code to iOS-Shortcuts-like shareable text
- Installing
- Usage
- Licence
- [Installing](#installing)
- [Usage](#usage)
- [Command-line Interface](#command-line-interface)
- [API Reference](#api-reference)
- [surplus.surplus()](#surplussurplus)
- [surplus.parse_query()](#surplusparse_query)
- [surplus.Localcode](#surpluslocalcode)
- [surplus.Latlong](#surpluslatlong)
- [Developing](#developing)
- [The format is wrong/different!](#the-format-is-wrongdifferent)
- [Licence](#licence)
```text
$ surplus 6PH59R3J+R9
@ -16,8 +24,10 @@ Singapore
```
```python
>>> import surplus
>>> surplus.surplus("6PH58RPQ+JW")
>>> from surplus import surplus, Localcode
>>> Localcode(code="8RPQ+JW", locality="Singapore").full_length()
(True, '6PH58RPQ+JW')
>>> surplus("6PH58RPQ+JW")
(True, 'Caldecott Stn Exit 4\nToa Payoh Link\n298106\nSingapore')
```
@ -31,19 +41,135 @@ pip install git+https://github.com/markjoshwel/surplus
## Usage
```text
usage: surplus [-h] [-d] pluscode
### Command-line Interface
plus code to iOS-Shortcuts-like shareable text
```text
usage: surplus [-h] [-d] query
Plus Code to iOS-Shortcuts-like shareable text
positional arguments:
pluscode full-length plus code including area code, e.g.: 6PH58QMF+FX
query full-length Plus Code (6PH58QMF+FX), local codes (8QMF+FX Singapore), or latlong (1.3336875, 103.7749375)
options:
-h, --help show this help message and exit
-d, --debug prints lat, long and reverser response dict to stderr
```
### API Reference
#### `surplus.surplus()`
pluscode to shareable text conversion function
- signature
```python
def surplus(
query: str | Localcode | Latlong,
reverser: Callable = Nominatim(user_agent="surplus").reverse,
debug: bool = False,
) -> tuple[bool, str]:
...
```
- arguments
- `query: str | surplus.Localcode | surplus.Latlong`
str - normal longcode (6PH58QMF+FX)
surplus.Localcode - shortcode with locality (8QMF+FX Singapore)
surplus.Latlong - latlong
- `reverser: Callable = geopy.geocoders.Nominatim(user_agent="surplus").reverser`
latlong to data function, accesses a dict from .raw attribute of return object
function should be able to take a string with two floats
```python
# code used by surplus
location: dict[str, Any] = reverser(f"{lat}, {lon}").raw
```
dict should be similar to geopy's geocoder provider .raw dicts
- `debug: bool = False`
prints lat, long and reverser response dict to stderr
- returns `tuple[bool, str]`
- `(True, <str>)`
conversion was successful, str is resultant text
- `(False, <str>)`
conversion failed, str is error message
---
#### `surplus.parse_query()`
function that parses a string Plus Code, local code or latlong into a str, surplus.Localcode or surplus.Latlong respectively
- signature:
```python
def parse_query(query: str) -> tuple[bool, str | Localcode | Latlong]:
```
- arguments:
- `query: str`
string Plus Code, local code or latlong
- returns `tuple[bool, str | Localcode | Latlong]`
- `(True, <str | Localcode | Latlong>)`
conversion was successful, second element is result
- `(False, <str>)`
conversion failed, str is error message
---
#### `surplus.Localcode`
`typing.NamedTuple` representing short Plus Code with locality
- parameters:
- `code: str`
Plus Code - e.g.: "8QMF+FX"
- `locality: str`
e.g.: "Singapore"
---
##### `surplus.Localcode.full_length()`
method that calculates full-length Plus Code using locality
- signature:
```python
def full_length(self) -> tuple[bool, str]:
```
- returns:
- `(True, <str>)`
conversion was successful, str is resultant Plus Code
- `(False, <str>)`
conversion failed, str is error message
---
#### `surplus.Latlong`
`typing.NamedTuple` representing a pair of latitude and longitude coordinates
- parameters:
- `lat: float`
latitudinal coordinate
- `long: float`
longitudinal coordinate
## Developing
Prerequisites:
@ -59,6 +185,19 @@ poetry install
poetry shell
```
## The format is wrong/different!
If surplus generates wrong text for a particular Plus Code,
[submit an issue](https://github.com/markjoshwel/surplus/issues/new).
Ensure you detail the following:
1. The erroneous Plus Code, local code or latlong, or a similar coordinate that reproduces the same error
2. Output from the terminal, with `--debug` enabled or `debug=True`
3. How it should look like instead
## Licence
surplus is free and unencumbered software released into the public domain.