Docs/readme reorg#52
Open
tilorspace wants to merge 2 commits into
Open
Conversation
- Trim README.md from 458 to ~110 lines: value prop, quick start, core features table (incl. Instruments/Instrument Templates), compatibility & limitations, indexed examples/notebooks, Community Projects link. - Move the full API cookbook verbatim into docs/usage-guide.md. - CONTRIBUTING.md now links DEVELOPING.md and the community repo's Guide to the RSpace Project / Getting Started / Code of Conduct. - Remove local SECURITY.md; org-wide policy at rspace-os/.github applies. - Fix stale pip version pin and Python version compatibility claim.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Reorganizes the repo documentation so the README is a concise landing page and the exhaustive API cookbook lives in a dedicated usage guide. No client code changes.
What changed
README.md (458 → ~110 lines): trimmed to a proper landing page — value prop, badges (PyPI/versions/license), quick start, a core-features table (now including Instruments & Instrument Templates, new in 2.7.0 / RSpace 2.24), a compatibility & limitations section, and indexed pointers to the examples, notebooks, and Community Projects.
docs/usage-guide.md (new, 413 lines): the full worked-example reference moved verbatim out of the README — PyFilesystem, document CRUD & search, attachments, folders/notebooks, forms, activity/audit trail, and export — with a table-of-contents and cross-links back to the README.
CONTRIBUTING.md: now points to DEVELOPING.md for local setup and to the community repo’s Guide to the RSpace Project / Getting Started / Code of Conduct instead of duplicating them.
SECURITY.md: removed — the org-wide policy at rspace-os/.github (https://github.com/rspace-os/.github/blob/main/SECURITY.md) applies.
Fixed a couple of stale claims: the pip install version pin and the Python-version compatibility statement (now 3.9+, matching pyproject.toml).
Why
The README had grown into a full API tutorial, burying the “what is this / how do I start” essentials. Splitting reference material into docs/usage-guide.md keeps the front page scannable while preserving every example.
A few things worth a quick check before you post:
Python version: the diff shows the old README claimed 3.7+ while the new docs say 3.9+ (per pyproject.toml). Confirm 3.9 is right.
Suggested title: docs: reorganize README, split out usage guide, drop redundant SECURITY.md
Want me to shorten this to a lighter version, or tweak the tone?I’ll read the PR diff to understand what changed.
This is a documentation reorganization PR. Here’s a description you can drop into the PR body:
Summary
Reorganizes the repo documentation so the README is a concise landing page and the exhaustive API cookbook lives in a dedicated usage guide. No client code changes.
What changed
README.md (458 → ~110 lines): trimmed to a proper landing page — value prop, badges (PyPI/versions/license), quick start, a core-features table (now including Instruments & Instrument Templates, new in 2.7.0 / RSpace 2.24), a compatibility & limitations section, and indexed pointers to the examples, notebooks, and Community Projects.
docs/usage-guide.md (new, 413 lines): the full worked-example reference moved verbatim out of the README — PyFilesystem, document CRUD & search, attachments, folders/notebooks, forms, activity/audit trail, and export — with a table-of-contents and cross-links back to the README.
CONTRIBUTING.md: now points to DEVELOPING.md for local setup and to the community repo’s Guide to the RSpace Project / Getting Started / Code of Conduct instead of duplicating them.
SECURITY.md: removed — the org-wide policy at rspace-os/.github (https://github.com/rspace-os/.github/blob/main/SECURITY.md) applies.
Fixed a couple of stale claims: the pip install version pin and the Python-version compatibility statement (now 3.9+, matching pyproject.toml).
Why
The README had grown into a full API tutorial, burying the “what is this / how do I start” essentials. Splitting reference material into docs/usage-guide.md keeps the front page scannable while preserving every example.