add lambda logo, fold sections, add python/error/log snippets
- Pull the rethink lambda logo (assets/img/logo.svg) into docs/assets and wire it as theme.logo + favicon — matches the Gitea brand mark. - standards.md: fold six thin sections into three fuller ones (Files and style / Documentation / Quality and error handling), each illustrated with python snippets, a flake8 output block, Do/Don't tabbed examples, a traceback, and a log line. Admonitions for the run-it-locally tip and the lib-logging note. - libraries.md: add a collapsible 'using a library' example (pyproject pin + import/usage python snippet). Verified in-browser: logo renders in the header, snippets/tabs/traceback/ log blocks render against the dark theme, libraries example expands. mkdocs build --strict clean. Signed-off-by: disqualifier <dev@disqualifier.me>
This commit is contained in:
dsql committed
1 parent
da47923088
commit
142a0dbff6
4 files changed
+151
-22
No files matched your search
@@ -0,0 +1,10 @@
|
|||||||
|
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1200 1200" width="32" height="32" role="img" aria-label="Lambda">
|
||||||
|
<defs>
|
||||||
|
<linearGradient id="plOrange" x1="0" y1="0" x2="0" y2="1">
|
||||||
|
<stop offset="0" stop-color="#ffae42"/>
|
||||||
|
<stop offset="1" stop-color="#f57c00"/>
|
||||||
|
</linearGradient>
|
||||||
|
</defs>
|
||||||
|
<path fill="url(#plOrange)" stroke="url(#plOrange)" stroke-width="26" stroke-linejoin="round" stroke-linecap="round"
|
||||||
|
d="M964.0,1153.5 L956.0,1153.5 L948.0,1153.5 L940.0,1153.5 L932.0,1153.5 L924.0,1153.5 L916.0,1153.5 L909.0,1152.5 L901.0,1152.5 L894.0,1151.5 L886.5,1151.0 L879.5,1150.0 L872.5,1149.0 L866.0,1147.5 L859.0,1146.5 L853.0,1144.5 L846.5,1143.0 L840.0,1141.5 L834.0,1139.5 L828.5,1137.0 L823.0,1134.5 L817.0,1132.5 L812.0,1129.5 L807.0,1126.5 L802.0,1123.5 L797.0,1120.5 L792.0,1117.5 L787.5,1114.0 L783.0,1110.5 L779.0,1106.5 L774.5,1103.0 L770.5,1099.0 L766.5,1095.0 L762.5,1091.0 L759.0,1086.5 L755.5,1082.0 L752.0,1077.5 L748.5,1073.0 L745.5,1068.0 L742.5,1063.0 L739.5,1058.0 L736.5,1053.0 L733.5,1048.0 L730.5,1043.0 L728.0,1037.5 L725.5,1032.0 L723.0,1026.5 L720.5,1021.0 L718.0,1015.5 L715.5,1010.0 L713.5,1004.0 L711.5,998.0 L709.5,992.0 L707.0,986.5 L705.0,980.5 L702.5,975.0 L700.5,969.0 L698.5,963.0 L696.5,957.0 L694.0,951.5 L692.0,945.5 L689.5,940.0 L687.5,934.0 L685.5,928.0 L683.5,922.0 L681.0,916.5 L679.0,910.5 L676.5,905.0 L674.5,899.0 L672.5,893.0 L670.5,887.0 L668.0,881.5 L666.0,875.5 L663.5,870.0 L661.5,864.0 L659.5,858.0 L657.5,852.0 L655.0,846.5 L653.0,840.5 L650.5,835.0 L648.5,829.0 L646.5,823.0 L644.5,817.0 L642.5,811.0 L640.0,805.5 L637.5,800.0 L635.5,794.0 L633.5,788.0 L631.5,782.0 L629.5,776.0 L627.0,770.5 L624.5,765.0 L622.5,759.0 L620.5,753.0 L618.5,747.0 L616.5,741.0 L614.0,735.5 L612.0,729.5 L609.5,724.0 L606.5,728.0 L604.5,734.0 L602.5,740.0 L599.5,745.0 L597.5,751.0 L595.5,757.0 L593.0,762.5 L590.5,768.0 L588.5,774.0 L585.5,779.0 L583.5,785.0 L581.5,791.0 L579.0,796.5 L576.5,802.0 L574.5,808.0 L572.0,813.5 L569.5,819.0 L567.5,825.0 L565.0,830.5 L562.5,836.0 L560.5,842.0 L558.0,847.5 L555.5,853.0 L553.5,859.0 L551.0,864.5 L548.5,870.0 L546.5,876.0 L544.0,881.5 L541.5,887.0 L539.5,893.0 L537.0,898.5 L534.5,904.0 L532.5,910.0 L530.0,915.5 L527.5,921.0 L525.5,927.0 L523.0,932.5 L520.5,938.0 L518.5,944.0 L516.0,949.5 L513.5,955.0 L511.5,961.0 L509.0,966.5 L506.5,972.0 L504.5,978.0 L502.0,983.5 L499.5,989.0 L497.5,995.0 L495.0,1000.5 L492.5,1006.0 L490.5,1012.0 L488.0,1017.5 L485.5,1023.0 L483.5,1029.0 L481.0,1034.5 L478.5,1040.0 L476.5,1046.0 L474.0,1051.5 L471.5,1057.0 L469.5,1063.0 L467.0,1068.5 L464.5,1074.0 L462.5,1080.0 L460.0,1085.5 L457.5,1091.0 L455.5,1097.0 L453.0,1102.5 L450.5,1108.0 L448.5,1114.0 L446.0,1119.5 L443.5,1125.0 L441.5,1131.0 L439.0,1136.5 L436.5,1142.0 L434.5,1148.0 L430.0,1151.5 L422.0,1151.5 L414.0,1151.5 L406.0,1151.5 L398.0,1151.5 L390.0,1151.5 L382.0,1151.5 L374.0,1151.5 L366.0,1151.5 L358.0,1151.5 L350.0,1151.5 L342.0,1151.5 L334.0,1151.5 L326.0,1151.5 L318.0,1151.5 L310.0,1151.5 L302.0,1151.5 L294.0,1151.5 L286.0,1151.5 L278.0,1151.5 L270.0,1151.5 L262.0,1151.5 L254.0,1151.5 L246.0,1151.5 L238.0,1151.5 L230.0,1151.5 L222.0,1151.5 L214.0,1151.5 L206.0,1151.5 L198.0,1151.5 L190.0,1151.5 L182.0,1151.5 L180.0,1148.5 L182.5,1143.0 L185.0,1137.5 L187.5,1132.0 L190.0,1126.5 L192.5,1121.0 L194.5,1115.0 L197.5,1110.0 L199.5,1104.0 L202.5,1099.0 L204.5,1093.0 L207.0,1087.5 L209.5,1082.0 L212.0,1076.5 L214.5,1071.0 L217.0,1065.5 L219.5,1060.0 L221.5,1054.0 L224.5,1049.0 L226.5,1043.0 L229.5,1038.0 L231.5,1032.0 L234.0,1026.5 L236.5,1021.0 L239.0,1015.5 L241.5,1010.0 L244.0,1004.5 L246.5,999.0 L248.5,993.0 L251.5,988.0 L253.5,982.0 L256.5,977.0 L258.5,971.0 L261.0,965.5 L263.5,960.0 L266.0,954.5 L268.5,949.0 L271.0,943.5 L273.5,938.0 L276.0,932.5 L278.5,927.0 L280.5,921.0 L283.5,916.0 L285.5,910.0 L288.0,904.5 L290.5,899.0 L293.0,893.5 L295.5,888.0 L298.0,882.5 L300.5,877.0 L303.0,871.5 L305.5,866.0 L307.5,860.0 L310.5,855.0 L312.5,849.0 L315.0,843.5 L317.5,838.0 L320.0,832.5 L322.5,827.0 L325.0,821.5 L327.5,816.0 L330.0,810.5 L332.5,805.0 L334.5,799.0 L337.5,794.0 L339.5,788.0 L342.5,783.0 L344.5,777.0 L347.0,771.5 L349.5,766.0 L352.0,760.5 L354.5,755.0 L357.0,749.5 L359.5,744.0 L361.5,738.0 L364.5,733.0 L366.5,727.0 L369.0,721.5 L371.5,716.0 L374.0,710.5 L376.5,705.0 L379.0,699.5 L381.5,694.0 L384.0,688.5 L386.5,683.0 L388.5,677.0 L391.5,672.0 L393.5,666.0 L396.0,660.5 L398.5,655.0 L401.0,649.5 L403.5,644.0 L406.0,638.5 L408.5,633.0 L411.0,627.5 L413.5,622.0 L415.5,616.0 L418.5,611.0 L420.5,605.0 L423.0,599.5 L425.5,594.0 L428.0,588.5 L430.5,583.0 L433.0,577.5 L435.5,572.0 L438.0,566.5 L440.5,561.0 L442.5,555.0 L445.5,550.0 L447.5,544.0 L450.5,539.0 L452.5,533.0 L455.0,527.5 L457.5,522.0 L460.0,516.5 L462.5,511.0 L465.0,505.5 L467.5,500.0 L469.5,494.0 L472.5,489.0 L474.5,483.0 L477.5,478.0 L479.5,472.0 L482.0,466.5 L484.5,461.0 L487.0,455.5 L489.5,450.0 L492.0,444.5 L494.5,439.0 L496.5,433.0 L499.5,428.0 L501.5,422.0 L504.0,416.5 L502.5,411.0 L500.0,405.5 L498.0,399.5 L495.5,394.0 L493.5,388.0 L491.5,382.0 L489.5,376.0 L487.0,370.5 L484.5,365.0 L482.0,359.5 L479.5,354.0 L477.5,348.0 L475.0,342.5 L472.5,337.0 L470.0,331.5 L467.5,326.0 L465.0,320.5 L462.5,315.0 L459.5,310.0 L457.0,304.5 L454.0,299.5 L451.0,294.5 L447.5,290.0 L444.5,285.0 L441.0,280.5 L437.5,276.0 L433.5,272.0 L429.0,268.5 L424.5,265.0 L419.5,262.0 L414.0,259.5 L408.0,257.5 L402.0,255.5 L395.5,254.0 L3Line truncated
|
||||||
|
</svg>
|
||||||
|
After Width: | Height: | Size: 9.0 KiB |
@@ -11,10 +11,44 @@ the repo, where the README and tags live.
|
|||||||
|
|
||||||
## Install
|
## Install
|
||||||
|
|
||||||
|
Pin a tag in your dependencies — never an unpinned branch:
|
||||||
|
|
||||||
```
|
```
|
||||||
<lib> @ git+https://git.rethinkstudios.io/rethink-public/<lib>.git@<tag>
|
<lib> @ git+https://git.rethinkstudios.io/rethink-public/<lib>.git@<tag>
|
||||||
```
|
```
|
||||||
|
|
||||||
|
??? example "Using a library — install, import, go"
|
||||||
|
|
||||||
|
Add it to your project's deps (e.g. `pyproject.toml`):
|
||||||
|
|
||||||
|
```toml
|
||||||
|
[project]
|
||||||
|
dependencies = [
|
||||||
|
"aioweb @ git+https://git.rethinkstudios.io/rethink-public/aioweb.git@v0.3.1",
|
||||||
|
]
|
||||||
|
```
|
||||||
|
|
||||||
|
Then use it — the README in each repo has the real surface; this is the shape:
|
||||||
|
|
||||||
|
```python
|
||||||
|
import asyncio
|
||||||
|
|
||||||
|
from aioweb import Session
|
||||||
|
|
||||||
|
|
||||||
|
async def main() -> None:
|
||||||
|
"""fetch a page through the shared async http session"""
|
||||||
|
async with Session() as web:
|
||||||
|
resp = await web.get("https://example.test")
|
||||||
|
print(resp.status, len(resp.content))
|
||||||
|
|
||||||
|
|
||||||
|
asyncio.run(main())
|
||||||
|
```
|
||||||
|
|
||||||
|
Need to bump a lib? Change the `@<tag>` and reinstall — versions live with the
|
||||||
|
lib, not in these docs.
|
||||||
|
|
||||||
<div id="lib-list" markdown="0">
|
<div id="lib-list" markdown="0">
|
||||||
<p class="lib-status">Loading libraries from Gitea…</p>
|
<p class="lib-status">Loading libraries from Gitea…</p>
|
||||||
</div>
|
</div>
|
||||||
|
|||||||
+105
-22
@@ -3,40 +3,123 @@
|
|||||||
The house standards every Rethink Studios project follows. They keep our code
|
The house standards every Rethink Studios project follows. They keep our code
|
||||||
consistent, readable, and predictable across the whole suite.
|
consistent, readable, and predictable across the whole suite.
|
||||||
|
|
||||||
## File hygiene
|
## Files and style
|
||||||
|
|
||||||
- Files end with a **single trailing newline** (LF / Unix line endings).
|
- Files end with a **single trailing newline** (LF / Unix line endings), and
|
||||||
- **No trailing whitespace** on any line.
|
carry **no trailing whitespace** on any line.
|
||||||
|
- **4 spaces** for indentation by default. Respect language norms — TS/JS use
|
||||||
|
**2 spaces**, Go uses **tabs** — and when editing an existing file, follow that
|
||||||
|
file's existing indentation.
|
||||||
|
- **flake8 clean**, max line length **120**. **Type hints** on public functions.
|
||||||
|
|
||||||
## Indentation
|
A well-formed module — module docstring, type hints, lowercase-start docstring:
|
||||||
|
|
||||||
- **4 spaces** by default.
|
```python
|
||||||
- Respect language norms: TS/JS use **2 spaces**, Go uses **tabs**.
|
"""async key/value store backed by a single json file"""
|
||||||
- When editing an existing file, follow that file's existing indentation.
|
|
||||||
|
|
||||||
## Docstrings and comments
|
from pathlib import Path
|
||||||
|
|
||||||
- Public functions get a **docstring**. Style: **lowercase-start, no trailing
|
|
||||||
period**.
|
def load_state(path: Path) -> dict[str, str]:
|
||||||
- Keep inline comments minimal — prefer docstrings. Use an inline comment only
|
"""read the json state file, returning an empty dict if it's missing"""
|
||||||
|
if not path.exists():
|
||||||
|
return {}
|
||||||
|
return _read_json(path)
|
||||||
|
```
|
||||||
|
|
||||||
|
flake8 tells you the moment you drift — keep the tree clean:
|
||||||
|
|
||||||
|
```text
|
||||||
|
$ flake8
|
||||||
|
./aiokv/store.py:14:80: E501 line too long (96 > 79 characters)
|
||||||
|
./aiokv/store.py:22:1: F401 'json' imported but unused
|
||||||
|
./aiokv/store.py:31:5: E303 too many blank lines (3)
|
||||||
|
```
|
||||||
|
|
||||||
|
!!! tip "Run it locally"
|
||||||
|
Wire the shared config into an alias so every project lints the same way:
|
||||||
|
`alias flake8='flake8 --config ~/.config/flake8'` (max line 120). See the
|
||||||
|
[Workflow](workflow.md#handy-shell-setup) page.
|
||||||
|
|
||||||
|
## Documentation
|
||||||
|
|
||||||
|
- Public functions get a **docstring** — **lowercase-start, no trailing period**.
|
||||||
|
- Keep inline comments minimal; prefer docstrings. Use an inline comment only
|
||||||
where the code is genuinely complex.
|
where the code is genuinely complex.
|
||||||
- Each module/file states its scope and purpose via a **module docstring**
|
- Each module/file states its scope and purpose via a **module docstring**
|
||||||
(header string) — **not** a license or copyright header.
|
(header string) — **not** a license or copyright header.
|
||||||
|
- Every library and project has a **README** with the install line, what it does,
|
||||||
|
and a usage example.
|
||||||
|
|
||||||
## READMEs
|
=== "Do"
|
||||||
|
|
||||||
Every library and project has a defined **README** covering:
|
```python
|
||||||
|
def mask_secret(value: str, keep: int = 4) -> str:
|
||||||
|
"""mask all but the last ``keep`` characters of a secret"""
|
||||||
|
if len(value) <= keep:
|
||||||
|
return "*" * len(value)
|
||||||
|
return "*" * (len(value) - keep) + value[-keep:]
|
||||||
|
```
|
||||||
|
|
||||||
- the install line,
|
=== "Don't"
|
||||||
- what it does,
|
|
||||||
- a usage example.
|
|
||||||
|
|
||||||
## Linting and types
|
```python
|
||||||
|
# Masks a secret. <- license-header-style noise, capitalized, trailing period
|
||||||
|
def mask_secret(value, keep=4): # no type hints
|
||||||
|
# loop over the chars and hide them
|
||||||
|
return "*" * (len(value) - keep) + value[-keep:] # crashes if short
|
||||||
|
```
|
||||||
|
|
||||||
- **flake8 clean**, max line length **120**.
|
## Quality and error handling
|
||||||
- **Type hints** on public functions.
|
|
||||||
|
|
||||||
## Error handling
|
**Fail loud** — never swallow exceptions. Catch the **specific** exception and
|
||||||
|
**log** it; don't paper over failures with a bare `except`.
|
||||||
|
|
||||||
- **Fail loud** — never swallow exceptions.
|
=== "Do"
|
||||||
- Catch the **specific** exception, and **log** it.
|
|
||||||
|
```python
|
||||||
|
import logging
|
||||||
|
|
||||||
|
log = logging.getLogger(__name__)
|
||||||
|
|
||||||
|
|
||||||
|
def fetch(url: str) -> bytes:
|
||||||
|
"""fetch ``url``, logging and re-raising on failure"""
|
||||||
|
try:
|
||||||
|
return _client.get(url).content
|
||||||
|
except TimeoutError:
|
||||||
|
log.warning("fetch timed out: %s", url)
|
||||||
|
raise
|
||||||
|
```
|
||||||
|
|
||||||
|
=== "Don't"
|
||||||
|
|
||||||
|
```python
|
||||||
|
def fetch(url):
|
||||||
|
try:
|
||||||
|
return _client.get(url).content
|
||||||
|
except Exception:
|
||||||
|
pass # swallowed — the caller has no idea anything broke
|
||||||
|
```
|
||||||
|
|
||||||
|
When something does break, a loud failure gives you a real traceback to act on:
|
||||||
|
|
||||||
|
```python-traceback
|
||||||
|
Traceback (most recent call last):
|
||||||
|
File "run.py", line 42, in <module>
|
||||||
|
data = fetch("https://example.test/feed")
|
||||||
|
File "aioweb/session.py", line 88, in fetch
|
||||||
|
return self._client.get(url).content
|
||||||
|
TimeoutError: request timed out after 30s
|
||||||
|
```
|
||||||
|
|
||||||
|
…and the log line that precedes it tells you where to look:
|
||||||
|
|
||||||
|
```text
|
||||||
|
2026-06-29 14:03:11,204 WARNING aioweb.session fetch timed out: https://example.test/feed
|
||||||
|
```
|
||||||
|
|
||||||
|
!!! note "Logging belongs to the app, not the library"
|
||||||
|
Libraries **emit only** — `log = logging.getLogger(__name__)` and nothing
|
||||||
|
else. Handlers, levels, and formatting are configured once at the
|
||||||
|
application entry point, so a lib never dictates how its host logs.
|
||||||
@@ -9,6 +9,8 @@ extra_css:
|
|||||||
theme:
|
theme:
|
||||||
name: material
|
name: material
|
||||||
language: en
|
language: en
|
||||||
|
logo: assets/logo.svg
|
||||||
|
favicon: assets/logo.svg
|
||||||
palette:
|
palette:
|
||||||
scheme: slate
|
scheme: slate
|
||||||
primary: custom
|
primary: custom
|
||||||
|
|||||||
Reference in new issue
Block a user