run-llama/workflows-py
1
0
Fork 0
mirror of https://github.com/run-llama/workflows-py.git synced 2026-07-21 04:05:25 -04:00
Code Issues 18 Packages Projects Releases 10 Wiki Activity

[PR #80] [CLOSED] docs: use pydoc-markdown to generate API reference #98

New Issue
Closed
opened 2026-02-16 02:16:34 -05:00 by yindo · 0 comments
yindo commented 2026-02-16 02:16:34 -05:00
Owner
Copy Link
Copy Source

📋 Pull Request Information

Original PR: https://github.com/run-llama/workflows-py/pull/80
Author: @masci
Created: 9/2/2025
Status: ❌ Closed

Base: main ← Head: massi/api-reference

📝 Commits (1)

  • c78d848 docs: use pydoc-markdown to generate API reference

📊 Changes

27 files changed (+2549 additions, -385 deletions)

View changed files

➖ docs/docs/api_reference/workflow/context.md (+0 -29)
➖ docs/docs/api_reference/workflow/decorators.md (+0 -4)
➖ docs/docs/api_reference/workflow/errors.md (+0 -1)
➖ docs/docs/api_reference/workflow/events.md (+0 -8)
➖ docs/docs/api_reference/workflow/handler.md (+0 -1)
➖ docs/docs/api_reference/workflow/index.md (+0 -3)
➖ docs/docs/api_reference/workflow/resource.md (+0 -1)
➖ docs/docs/api_reference/workflow/retry_policy.md (+0 -5)
➖ docs/docs/api_reference/workflow/workflow.md (+0 -5)
➕ docs/docs/workflows/v2/api_reference.md (+1953 -0)
📝 docs/docs/workflows/v2/index.md (+1 -1)
📝 docs/mkdocs.yml (+5 -7)
📝 docs/pyproject.toml (+23 -1)
📝 docs/uv.lock (+245 -1)
📝 src/workflows/context/context.py (+104 -105)
📝 src/workflows/context/serializers.py (+19 -19)
📝 src/workflows/context/state_store.py (+30 -33)
📝 src/workflows/decorators.py (+14 -14)
📝 src/workflows/events.py (+51 -50)
📝 src/workflows/handler.py (+22 -22)

...and 7 more files

📄 Description

Instead of building the reference with mkdocs, we use pydoc-markdown to generate a markdown file from the docstrings in the sources. mkdocs will then treat this markdown file as any other documentation page.

Why?

  • This way we can version the generated API docs
  • The new documentation website will benefit from getting a markdown file ready to be rendered

Implications:

  • Cross-references have a different format in pydoc-markdown so I had to change the docstrings
  • The workflow section under the "API Reference" in the soon-to-be old documentation website has been removed
  • Right now the generated markdown file is checked in, to be decided if it's better for the new docs website to generate it on-the-fly

🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.

## 📋 Pull Request Information **Original PR:** https://github.com/run-llama/workflows-py/pull/80 **Author:** [@masci](https://github.com/masci) **Created:** 9/2/2025 **Status:** ❌ Closed **Base:** `main` ← **Head:** `massi/api-reference` --- ### 📝 Commits (1) - [`c78d848`](https://github.com/run-llama/workflows-py/commit/c78d848872199b0e8887b6669af2b972f91673c0) docs: use pydoc-markdown to generate API reference ### 📊 Changes **27 files changed** (+2549 additions, -385 deletions) <details> <summary>View changed files</summary> ➖ `docs/docs/api_reference/workflow/context.md` (+0 -29) ➖ `docs/docs/api_reference/workflow/decorators.md` (+0 -4) ➖ `docs/docs/api_reference/workflow/errors.md` (+0 -1) ➖ `docs/docs/api_reference/workflow/events.md` (+0 -8) ➖ `docs/docs/api_reference/workflow/handler.md` (+0 -1) ➖ `docs/docs/api_reference/workflow/index.md` (+0 -3) ➖ `docs/docs/api_reference/workflow/resource.md` (+0 -1) ➖ `docs/docs/api_reference/workflow/retry_policy.md` (+0 -5) ➖ `docs/docs/api_reference/workflow/workflow.md` (+0 -5) ➕ `docs/docs/workflows/v2/api_reference.md` (+1953 -0) 📝 `docs/docs/workflows/v2/index.md` (+1 -1) 📝 `docs/mkdocs.yml` (+5 -7) 📝 `docs/pyproject.toml` (+23 -1) 📝 `docs/uv.lock` (+245 -1) 📝 `src/workflows/context/context.py` (+104 -105) 📝 `src/workflows/context/serializers.py` (+19 -19) 📝 `src/workflows/context/state_store.py` (+30 -33) 📝 `src/workflows/decorators.py` (+14 -14) 📝 `src/workflows/events.py` (+51 -50) 📝 `src/workflows/handler.py` (+22 -22) _...and 7 more files_ </details> ### 📄 Description Instead of building the reference with mkdocs, we use `pydoc-markdown` to generate a markdown file from the docstrings in the sources. mkdocs will then treat this markdown file as any other documentation page. Why? - This way we can version the generated API docs - The new documentation website will benefit from getting a markdown file ready to be rendered Implications: - Cross-references have a different format in `pydoc-markdown` so I had to change the docstrings - The `workflow` section under the "API Reference" in the soon-to-be old documentation website has been removed - Right now the generated markdown file is checked in, to be decided if it's better for the new docs website to generate it on-the-fly --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>
yindo added the pull-request label 2026-02-16 02:16:34 -05:00
yindo closed this issue 2026-02-16 02:16:34 -05:00
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
bug
enhancement
enhancement
good first issue
pull-request
Mirrored from GitHub Pull Request
 question
No Label pull-request
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
yindo
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: run-llama/workflows-py#98
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?