Restructure developer docs by language#42
Merged
christophdb merged 18 commits intomainfrom Mar 19, 2026
Merged
Conversation
Reorganize the entire documentation from the old structure (Scripting / Client APIs as top-level sections) to a language-first structure (Python / JavaScript / PHP / Ruby). - Python: unified section with new Getting Started covering both script and client authentication contexts - JavaScript: single section with Scripting API and Client API subsections - PHP and Ruby: moved from clients/ to own top-level sections - New landing page focused on developers, with language selection table - Examples and common questions removed (moved to user help at seatable.com/help/scripts/) - Coding for beginners removed (moved to user help) - All internal links updated to new paths
JavaScript: Merge Scripting API and Client API into a single reference. The two APIs are essentially the same - only parameter names differed. Methods unique to the browser context (context, output, utilities, filter/queryset) are documented on a dedicated "Scripting Features" page. Reduces 18 JS files to 11 with zero content duplication. PHP: Split the single monolithic page into Getting Started, Examples, and API Reference for better navigation.
The file upload example was a workaround for missing file support in the seatable-api package. Move it to a dedicated "Files" page that explains the limitation and documents the REST API workflow.
- Python: remove "Objects & Methods" and "Query with SQL" subgroups, list all pages flat like JavaScript. Remove objects/index.md intro page (content was redundant with Getting Started). - PHP: remove index.md intro page, merge its content into Getting Started which is now the entry point. - All sections now follow the same pattern: Getting Started as first page, then topic pages listed flat.
Move Getting Started content into index.md for each language so clicking the section name in the sidebar shows the page directly (using MkDocs Material navigation.indexes). Remove redundant "-- Getting Started" from page titles.
Landing page: remove data model embed, deduplicate API reference link, add Ruby to language table, fix broken Python link, use example admonition for other languages hint. Get support: fix email to sales@seatable.com, fix help URL, clean up language.
Move comparison table above auth details for better overview. Collapse account auth and expiration handling into detail boxes. Remove libraries section (now covered by table row). Remove indentation warning. Fix links.
Add comparison table matching Python structure. Remove generic common errors section. Keep async and API limits as focused sections. Remove scripting setup duplication.
Simplify auth flow to the common case (API Token to Base Token). Collapse account-level auth and self-hosted setup into detail boxes. Remove v0.2 incompatibility notice.
- Fix 5 broken links to removed common_questions.md (inline the advice instead) - Fix "llink" typo throughout links.md - Remove duplicate paragraph in rows.md (SQL backticks warning) - Merge users.md (1 method) into accounts.md - Merge big_data.md (1 method) into rows.md
Add documentation for methods that exist in seatable-api-python source code but were missing from the developer docs: - rows: filter(), filter_rows() for non-SQL row filtering - links: batch_add_links(), batch_remove_links() - communication-utils: send_email() - accounts: get_related_users() - context: get_setting_by_key() Verified against github.com/seatable/seatable-api-python source. Excluded internal methods (load_account_info) and niche features (send_wechat_msg, workflow tasks) per product decision.
- Separate get_user_info and get_related_users back into users.md (they are Base methods, not Account methods) - Move SQL docs from python/sql/ to sql/ as own top-level section (SQL is language-agnostic, used by both Python and JavaScript) - Update all internal links to new SQL paths
SQL: Split the 299-line introduction.md into 6 focused pages: introduction (overview), SELECT, INSERT/UPDATE/DELETE, clauses, data types, and extended syntax. Functions reference unchanged. Python: Restore users.md as separate page (get_user_info and get_related_users are Base methods, not Account methods).
Make SQL section clickable by using index.md as section page. Clarify that SQL is used through Python/JavaScript API, not standalone. Remove redundant manual section links. Move backticks hint to clauses page. Update all internal links.
Add muffet link checker that runs before deploy, matching the setup from seatable-admin-docs. Deploy now depends on successful link check. Also fix typo in workflow name (setable -> seatable).
Activate mkdocs-redirects plugin with complete mapping from old scripts/*, clients/*, introduction/* paths to the new structure. Examples redirect to the language intro page (content moved to seatable.com/help). Remove unused mermaid test file.
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
What moved where
Open items (not in this PR)
Test plan
mkdocs build --strictlocally