Skip to content

docs: restructure the README and split the reference into docs/ - #12

Merged
ogorzalka merged 2 commits into
mainfrom
docs/readme-restructure
Oct 15, 2026
Merged

ogorzalka merged 2 commits into
mainfrom
docs/readme-restructure

Conversation

@ogorzalka

Copy link
Copy Markdown
Member

Stacked on #11.

The README had grown to ~1900 lines, was centred on PostQuery and was partly stale. It is now a short overview, with the reference split into pages under docs/:

  • README.md: installation, quick start, the query classes, index
  • docs/concepts.md (start here), results.md, upgrading.md
  • docs/post-query.md, term-query.md, user-query.md, comment-query.md, site-network-query.md
  • docs/tax-query.md, meta-query.md, date-query.md

How it was checked

  • Every example's output is generated by running the code, not written by hand (72 examples).
  • Every public method of the 13 classes appears in the docs; every method called in a snippet exists; every internal link and anchor resolves.
  • The method → WordPress argument tables were checked by calling each method (194 pairs).
  • The "before" column of upgrading.md was checked against the 1.0.3 tag.
  • Statements about WordPress behaviour (LIKE wrapping, search wildcards, offset needing a limit...) were checked in the WordPress source.

Two code fixes found while documenting (separate commit)

  • PostQuery::orderBy() sent any direction as is; it now throws a QueryException like the other classes.
  • Search docblocks: users need a * for a partial match, sites and networks always match 'contains'.

Pest: 242 passed.

…cblocks

- PostQuery::orderBy() sent any direction to WordPress as is; it now throws a QueryException like the other query classes
- search docblocks: users need a * for a partial match, sites and networks always match 'contains'
- README: overview, quick start, query classes, index
- docs/concepts.md, results.md, upgrading.md
- one page per query class and per sub-query, with examples whose output is generated from the code
- everything that was stale is rewritten (permission, date hours, pagename, ofType, LIKE...)
@ogorzalka
ogorzalka changed the base branch from feat/site-network-query to main October 15, 2026 14:07
@ogorzalka
ogorzalka merged commit c0c663d into main Oct 15, 2026
2 checks passed
@ogorzalka
ogorzalka deleted the docs/readme-restructure branch October 15, 2026 14:12
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant