Skip to content

Commit f137191

Browse files
mgarcia01752mgarcia01752
committed
Streamline README onboarding and split Postman install/import guidance into linkable docs pages
- keep README lean with a shorter Start Here section and clickable starter links - move Postman Desktop download/install guidance into a dedicated Ubuntu/Windows doc - move Postman import, globals setup, and collection navigation guidance into a dedicated doc - add clickable links to collection, environment, and globals JSON files in import and troubleshooting sections - simplify user guide by linking to the dedicated import/navigation doc instead of duplicating setup steps - update docs index to include the new Postman install and import/navigation documents - standardize local command examples around source .venv/bin/activate and direct shebang-based tool execution - update install.sh output and generated docs command examples to match the activated-venv workflow - 2026-02-22 18:01:30
1 parent b914b5f commit f137191

48 files changed

Lines changed: 1621 additions & 150 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.github/workflows/python-ci.yml‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
name: Python CI (Ubuntu)
2+
3+
on:
4+
push:
5+
branches:
6+
- main
7+
- hot-fix
8+
pull_request:
9+
10+
permissions:
11+
contents: read
12+
13+
jobs:
14+
test:
15+
runs-on: ubuntu-latest
16+
strategy:
17+
fail-fast: false
18+
matrix:
19+
python-version: ["3.10", "3.11", "3.12"]
20+
21+
steps:
22+
- name: Checkout repository
23+
uses: actions/checkout@v4
24+
25+
- name: Set up Python
26+
uses: actions/setup-python@v5
27+
with:
28+
python-version: ${{ matrix.python-version }}
29+
30+
- name: Install dependencies
31+
run: |
32+
python -m pip install --upgrade pip setuptools wheel
33+
python -m pip install -e ".[dev]"
34+
35+
- name: Validate visual sanitization
36+
run: python tools/sanitize.py --check
37+
38+
- name: Validate generated visual docs
39+
run: python tools/docs/build_visual_docs.py --check
40+
41+
- name: Run tests
42+
run: python -m pytest -q

‎CODING_AGENTS.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -9,8 +9,8 @@
99
- Use the PyPNM default generic placeholders:
1010
- MAC: `aa:bb:cc:dd:ee:ff`
1111
- system_description JSON: `{"HW_REV":"1.0","VENDOR":"LANCity","BOOTR":"NONE","SW_REV":"1.0.0","MODEL":"LCPET-3"}`
12-
- Before committing visual JSON fixtures, run `.venv/bin/python tools/sanitize.py --check` (check only) or `.venv/bin/python tools/sanitize.py --fix` (apply changes) to sanitize MAC/sysDescr metadata.
13-
- Version source of truth is the repo `VERSION` file. When bumping versions, use `.venv/bin/python tools/support/bump_version.py --version X.Y.Z` so both `VERSION` and `pyproject.toml` stay in sync.
12+
- Before committing visual JSON fixtures, activate the repo venv (`source .venv/bin/activate`) and run `tools/sanitize.py --check` (check only) or `tools/sanitize.py --fix` (apply changes) to sanitize MAC/sysDescr metadata.
13+
- Version source of truth is the repo `VERSION` file. After activating the repo venv, use `tools/support/bump_version.py --version X.Y.Z` so both `VERSION` and `pyproject.toml` stay in sync.
1414

1515
## Tooling Layout (Required)
1616

‎README.md‎

Lines changed: 25 additions & 37 deletions
Original file line numberDiff line numberDiff line change
@@ -1,63 +1,51 @@
11
# Postman PyPNMApps API Collections
22

3-
This repository contains Postman collections, environment/globals files, and example visualizers for PyPNM API workflows.
3+
[![Python CI (Ubuntu)](https://github.com/PyPNMApps/Postman-PyPNMApps-API/actions/workflows/python-ci.yml/badge.svg)](https://github.com/PyPNMApps/Postman-PyPNMApps-API/actions/workflows/python-ci.yml)
4+
[![MkDocs Site Build](https://github.com/PyPNMApps/Postman-PyPNMApps-API/actions/workflows/mkdocs-site-build.yml/badge.svg)](https://github.com/PyPNMApps/Postman-PyPNMApps-API/actions/workflows/mkdocs-site-build.yml)
5+
[![MkDocs Pages Deploy](https://github.com/PyPNMApps/Postman-PyPNMApps-API/actions/workflows/mkdocs-pages-deploy.yml/badge.svg)](https://github.com/PyPNMApps/Postman-PyPNMApps-API/actions/workflows/mkdocs-pages-deploy.yml)
6+
[![MkDocs](https://img.shields.io/badge/docs-MkDocs-526CFE?logo=materialformkdocs&logoColor=white)](https://www.mkdocs.org/)
7+
[![License: Apache-2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE)
8+
[![Docs](https://img.shields.io/badge/docs-GitHub%20Pages-0A66C2)](https://pypnmapps.github.io/Postman-PyPNMApps-API/)
49

5-
## What This Repo Provides
10+
This repository contains Postman collections, environment/globals files, and example visualizers for PyPNM API workflows.
611

7-
- `postman/collections/PyPNM.postman_collection.json` (primary collection)
8-
- `postman/collections/PyPNM-CMTS.postman_collection.json` (placeholder shell)
9-
- `postman/environments/PyPNM Remote Server.postman_environment.json`
10-
- `postman/globals/workspace.postman_globals.json`
11-
- `visual/` example Postman Visualizer templates + sample data
12+
It includes:
13+
- Postman collections (`PyPNM`, `PyPNM-CMTS`)
14+
- environment and globals exports
15+
- `visual/` example Postman Visualizer HTML + JSON fixtures
1216

1317
## Basic Setup
1418

15-
1. Install Postman Desktop: `https://www.postman.com/downloads/`
19+
1. Install Postman Desktop (Ubuntu/Windows): `docs/postman-install.md`
1620
2. Clone this repository:
1721

1822
```bash
1923
git clone https://github.com/PyPNMApps/Postman-PyPNMApps-API.git
2024
cd Postman-PyPNMApps-API
2125
```
2226

23-
3. In Postman, import:
24-
- `postman/collections/PyPNM.postman_collection.json`
25-
- `postman/collections/PyPNM-CMTS.postman_collection.json`
26-
- `postman/environments/PyPNM Remote Server.postman_environment.json`
27-
- `postman/globals/workspace.postman_globals.json`
28-
29-
4. Set `pypnm_url` in Postman Globals (example: `http://127.0.0.1:8000`)
27+
3. Import collections/environment/globals and configure `pypnm_url`:
28+
- `docs/postman-import-and-navigation.md`
3029

31-
Important:
32-
- Collection requests use `{{pypnm_url}}` (global), while the provided environment includes `base_url`.
33-
34-
## Local Tooling (Repo Maintenance)
35-
36-
This repo uses local Python tooling in `tools/` for sanitization, versioning, and release workflows.
30+
## Install (Local Tooling + Docs)
3731

3832
```bash
3933
./install.sh
4034
```
4135

42-
Common commands:
36+
Run the local MkDocs site (default local docs port for this repo: `8030`):
4337

4438
```bash
45-
.venv/bin/python tools/sanitize.py --check
46-
.venv/bin/python tools/sanitize.py --fix
47-
.venv/bin/python tools/support/bump_version.py --version 0.1.1 --check
48-
.venv/bin/python tools/release/release.py --version-info
49-
./tools/git/git-save.sh --help
50-
./tools/git/git-push.sh --help
39+
source .venv/bin/activate
40+
tools/docs/build_visual_docs.py
41+
mkdocs serve -a 127.0.0.1:8030
5142
```
5243

53-
Version source of truth:
54-
- `VERSION` (must stay in sync with `pyproject.toml`)
55-
56-
## Documentation
44+
Open:
45+
- `http://127.0.0.1:8030/`
5746

58-
Detailed instructions were moved to `docs/`:
47+
## Start Here
5948

60-
- `docs/docs-index.md` (docs index)
61-
- `docs/user-guide.md` (full Postman import/use walkthrough)
62-
- `docs/tools.md` (sanitize/version/release/git helpers)
63-
- `docs/release.md` (release process and versioning)
49+
- [Docs Home](docs/docs-index.md)
50+
- [Postman Install (Ubuntu/Windows)](docs/postman-install.md)
51+
- [Postman Import and Navigation](docs/postman-import-and-navigation.md)

‎docs/docs-index.md‎

Lines changed: 13 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,8 @@ This directory contains user documentation for working with the Postman PyPNMApp
44

55
## Documents
66

7+
- `docs/postman-install.md` - Postman Desktop download/install steps for Ubuntu and Windows.
8+
- `docs/postman-import-and-navigation.md` - Import Postman files, configure globals, and navigate collections.
79
- `docs/user-guide.md` - End-user setup and Postman import/use instructions.
810
- `docs/tools.md` - Local developer tooling (`sanitize`, `bump_version`, `release`, `git-save`, `git-push`).
911
- `docs/release.md` - Versioning and release workflow (`VERSION` source of truth).
@@ -14,13 +16,15 @@ This directory contains user documentation for working with the Postman PyPNMApp
1416

1517
1. Create the local Python virtual environment:
1618
- `./install.sh`
17-
2. Run sanitization checks:
18-
- `.venv/bin/python tools/sanitize.py --check`
19-
3. Review version state:
19+
2. Activate the virtual environment:
20+
- `source .venv/bin/activate`
21+
3. Run sanitization checks:
22+
- `tools/sanitize.py --check`
23+
4. Review version state:
2024
- `cat VERSION`
21-
4. Run tests:
22-
- `.venv/bin/python -m pytest -q`
23-
5. Generate visual docs pages:
24-
- `.venv/bin/python tools/docs/build_visual_docs.py`
25-
6. Serve docs locally:
26-
- `.venv/bin/mkdocs serve`
25+
5. Run tests:
26+
- `pytest -q`
27+
6. Generate visual docs pages:
28+
- `tools/docs/build_visual_docs.py`
29+
7. Serve docs locally:
30+
- `mkdocs serve -a 127.0.0.1:8030`

‎docs/postman-import-and-navigation.md‎

Lines changed: 64 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,64 @@
1+
# Postman Import and Navigation
2+
3+
Use this guide after installing Postman and cloning the repository.
4+
5+
## Import Files Into Postman
6+
7+
In Postman, import the following files:
8+
9+
- [`postman/collections/PyPNM.postman_collection.json`](../postman/collections/PyPNM.postman_collection.json)
10+
- [`postman/collections/PyPNM-CMTS.postman_collection.json`](../postman/collections/PyPNM-CMTS.postman_collection.json)
11+
- [`postman/environments/PyPNM Remote Server.postman_environment.json`](../postman/environments/PyPNM%20Remote%20Server.postman_environment.json)
12+
- [`postman/globals/workspace.postman_globals.json`](../postman/globals/workspace.postman_globals.json)
13+
14+
Recommended import flow:
15+
16+
1. Open Postman Desktop
17+
2. Click `Import`
18+
3. Select `Files`
19+
4. Choose the files listed above
20+
5. Confirm import
21+
22+
## Configure Base URL / Globals
23+
24+
Set `pypnm_url` in Postman Globals.
25+
26+
Example:
27+
28+
- `http://127.0.0.1:8000`
29+
30+
Important:
31+
32+
- Collection requests use `{{pypnm_url}}` (global variable)
33+
- The provided environment file includes `base_url`
34+
- If you prefer environment-only configuration, update the collection requests to use `{{base_url}}`
35+
36+
## Navigate the Imported Content
37+
38+
### Collections
39+
40+
- `PyPNM` (primary collection)
41+
- `PyPNM-CMTS` (placeholder shell)
42+
43+
### Good First Request
44+
45+
Use a simple health check first:
46+
47+
1. Open [`PyPNM` collection](../postman/collections/PyPNM.postman_collection.json)
48+
2. Open `Health` folder
49+
3. Open `Health` request
50+
4. Confirm `pypnm_url` is set
51+
5. Click `Send`
52+
53+
### Common Next Areas
54+
55+
- `SingleCapture` for single-capture workflows and visualizers
56+
- `MultiCapture` for multi-capture operations and analysis flows
57+
- `FileManager` for file workflow endpoints
58+
- `System` / `Health` for service checks and system actions
59+
60+
## Troubleshooting Import Setup
61+
62+
- If requests fail immediately, confirm `pypnm_url` is set in [Globals (`workspace.postman_globals.json`)](../postman/globals/workspace.postman_globals.json)
63+
- If variables appear unresolved, verify [`workspace.postman_globals.json`](../postman/globals/workspace.postman_globals.json) imported successfully
64+
- If you use the environment value (`base_url`) instead, verify the imported environment [`PyPNM Remote Server.postman_environment.json`](../postman/environments/PyPNM%20Remote%20Server.postman_environment.json) and ensure request URLs in [`PyPNM.postman_collection.json`](../postman/collections/PyPNM.postman_collection.json) were updated from `{{pypnm_url}}`

‎docs/postman-install.md‎

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
# Install Postman Desktop (Ubuntu and Windows)
2+
3+
## Download
4+
5+
- Official Postman downloads page: `https://www.postman.com/downloads/`
6+
7+
## Windows
8+
9+
1. Open the Postman downloads page.
10+
2. Download the **Windows 64-bit** desktop installer.
11+
3. Run the installer.
12+
4. Launch Postman and sign in (optional).
13+
14+
## Ubuntu (Desktop)
15+
16+
Use the Postman downloads page to get the Linux desktop package, then install it.
17+
18+
Common install flow (tarball-based):
19+
20+
1. Download the Linux package from the Postman downloads page.
21+
2. Extract it.
22+
3. Launch the Postman executable from the extracted directory.
23+
24+
Example commands (adjust the filename if needed):
25+
26+
```bash
27+
cd ~/Downloads
28+
tar -xzf postman-linux-x64.tar.gz
29+
./Postman/Postman
30+
```
31+
32+
Optional (system-wide install location):
33+
34+
```bash
35+
sudo rm -rf /opt/Postman
36+
sudo mv ~/Downloads/Postman /opt/Postman
37+
/opt/Postman/Postman
38+
```
39+
40+
## Verify
41+
42+
- Postman Desktop opens successfully
43+
- You can access the `Import` button in the app UI
44+
45+
## Next Step
46+
47+
- Continue with `docs/user-guide.md` to import the PyPNM Postman collections and configure globals.

‎docs/release.md‎

Lines changed: 10 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -14,16 +14,18 @@ Do not manually update only one of them.
1414
Use the bump tool to keep both files synchronized:
1515

1616
```bash
17-
.venv/bin/python tools/support/bump_version.py --version 0.1.1 --check
18-
.venv/bin/python tools/support/bump_version.py --version 0.1.1
17+
source .venv/bin/activate
18+
tools/support/bump_version.py --version 0.1.1 --check
19+
tools/support/bump_version.py --version 0.1.1
1920
```
2021

2122
## Release Flow
2223

2324
Use:
2425

2526
```bash
26-
.venv/bin/python tools/release/release.py --no-push
27+
source .venv/bin/activate
28+
tools/release/release.py --no-push
2729
```
2830

2931
What it does:
@@ -43,8 +45,9 @@ What it does:
4345
## Recommended Sequence
4446

4547
```bash
46-
.venv/bin/python tools/sanitize.py --check
47-
.venv/bin/python -m pytest -q
48-
.venv/bin/python tools/support/bump_version.py --version 0.1.1 --check
49-
.venv/bin/python tools/release/release.py --version 0.1.1 --no-push
48+
source .venv/bin/activate
49+
tools/sanitize.py --check
50+
pytest -q
51+
tools/support/bump_version.py --version 0.1.1 --check
52+
tools/release/release.py --version 0.1.1 --no-push
5053
```

‎docs/tools.md‎

Lines changed: 11 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,7 @@ Create the local virtual environment and install dev dependencies:
88

99
```bash
1010
./install.sh
11+
source .venv/bin/activate
1112
```
1213

1314
## Visual Docs Generator (MkDocs)
@@ -25,9 +26,9 @@ Purpose:
2526
Usage:
2627

2728
```bash
28-
.venv/bin/python tools/docs/build_visual_docs.py
29-
.venv/bin/python tools/docs/build_visual_docs.py --check
30-
.venv/bin/mkdocs serve
29+
tools/docs/build_visual_docs.py
30+
tools/docs/build_visual_docs.py --check
31+
mkdocs serve -a 127.0.0.1:8030
3132
```
3233

3334
Notes:
@@ -50,8 +51,8 @@ Purpose:
5051
Usage:
5152

5253
```bash
53-
.venv/bin/python tools/sanitize.py --check
54-
.venv/bin/python tools/sanitize.py --fix
54+
tools/sanitize.py --check
55+
tools/sanitize.py --fix
5556
```
5657

5758
Modes:
@@ -72,8 +73,8 @@ Purpose:
7273
Usage:
7374

7475
```bash
75-
.venv/bin/python tools/support/bump_version.py --version 0.1.1 --check
76-
.venv/bin/python tools/support/bump_version.py --version 0.1.1
76+
tools/support/bump_version.py --version 0.1.1 --check
77+
tools/support/bump_version.py --version 0.1.1
7778
```
7879

7980
## Release Tool
@@ -89,9 +90,9 @@ Purpose:
8990
Usage:
9091

9192
```bash
92-
.venv/bin/python tools/release/release.py --version-info
93-
.venv/bin/python tools/release/release.py --no-push
94-
.venv/bin/python tools/release/release.py --version 0.1.1 --no-push
93+
tools/release/release.py --version-info
94+
tools/release/release.py --no-push
95+
tools/release/release.py --version 0.1.1 --no-push
9596
```
9697

9798
## Git Convenience Tools

0 commit comments

Comments
 (0)