skills/mims-harvard__tooluniverse
1
0
Fork 0
mirror of https://github.com/mims-harvard/ToolUniverse.git synced 2026-09-19 07:31:47 +08:00
Code Issues Packages Projects Releases Wiki Activity
Files
08246bcd4db4d12678d9263b326aa8bbe6f1e47d
mims-harvard__tooluniverse/docs/conf.py
T
Shanghua Gao 08246bcd4d docs: expand redirect map (15 more paper-cited legacy paths) (#211) 
* docs: expand redirect map with 15 additional legacy paths

Adds redirects for paths uncovered in a second-pass audit against
the live published site. Each destination verified to return HTTP 200
on https://zitniklab.hms.harvard.edu/ToolUniverse/.

New /tutorials/ → /guide/, /tools/, /expand_tooluniverse/ redirects:
- make_your_data_searchable, make_your_data_agent_searchable,
  build_search_and_share_datastores → guide/make_your_data_agent_searchable
- skills → guide/skills_showcase
- tool_finder → guide/finding_tools
- overview → guide/index
- remote_tools → tools/remote_tools
- mcp_integration → expand_tooluniverse/remote_tools/mcp_integration

Top-level legacy pages (404 at root, now redirected):
- getting_started → guide/python_guide
- deployment, contributing, changelog → about/<page>
- faq → help/faq

Local build confirms all 22 redirect stubs generate and that every
destination file exists in the build output.

* docs: fix broken sphinx-tabs, dead toctrees, orphan pages, missing image

Build now produces 0 warnings/errors of these structural categories
(down from ~280 such issues):

- Re-enable sphinx_tabs.tabs extension (3.5.0 supports Sphinx 9.x);
  fixes 7 broken "Unknown directive type tabs" errors that made
  help/faq.html and help/troubleshooting.html render incomplete.
- Drop 25+ dead toctree entries in api/modules.rst and
  api/tooluniverse.rst that referenced per-module pages never
  generated by sphinx-apidoc; modules.rst now points at the existing
  comprehensive tooluniverse autodoc page.
- Wire 16 orphan pages into the master toctree so they're reachable
  from the navigation, including tooluniverse_case_study,
  visualization_tutorial, expert_feedback, literature_search_web_ui,
  euhealth, logging, openrouter, streaming, vllm, wechat_community,
  simbad_tools, the guide/index landing page, and the full
  expand_tooluniverse sub-tree.
- Remove three stale ":doc:" links to old/{quickstart,installation,
  getting_started} from sitemap.rst (those directories are excluded
  from the build) and mark sitemap.rst as :orphan: since it's a
  parallel nav surface by design.
- Mark MCP_TASKS_GUIDE.md as orphan and exclude the internal
  DOCUMENTATION_STRUCTURE.md meta-doc from the build.
- Add the missing tools/remote/ui.jpg referenced by the remote
  expert_feedback page (previously: broken image).

* docs: eliminate all 49 structural Sphinx ERRORs (broken tables, directives, headings)

Round-3 build cleanup. Builds now finish with 0 structural ERRORs of any
category (previous: 49 ERRORs spread across 20 files). Total
warnings/errors dropped from 280 → 114; the remaining 114 are all in
Python source-file docstrings (out of scope for a docs PR).

Categories fixed:

**Malformed tables** (8 files)

  Replace ASCII grid tables with mis-aligned pipes and inline-markdown
  pipe tables (which RST mis-parses as substitution references) with
  ``list-table`` directives that render correctly across all themes:

  - guide/literature_search_tools_tutorial.rst (two tables)
  - guide/cache_system.rst (env-var table whose first column overflowed)
  - guide/clinical_guidelines_tools.rst
  - guide/make_your_data_agent_searchable.rst
  - expand_tooluniverse/contributing/index.rst
  - expand_tooluniverse/contributing/remote_tools.rst
  - expand_tooluniverse/reference/index.rst

**list-table indentation** (3 files)

  Option lines and list items were indented with 1 space (only valid for
  3-space) so Sphinx silently dropped them and reported "exactly one
  bullet list expected":

  - guide/finding_tools.rst
  - guide/http_api.rst
  - guide/tools.rst

**Code-block separators** (5 files, ~30 directives)

  Add the required blank line between an introductory paragraph and a
  following ``.. code-block::``. Without it, Sphinx treated the directive
  as a continuation of the paragraph and emitted "Unexpected indentation"
  for every line of the code:

  - guide/literature_search_tools_tutorial.rst
  - expand_tooluniverse/quick_start.rst
  - expand_tooluniverse/contributing/local_tools.rst
  - expand_tooluniverse/contributing/remote_tools.rst
  - guide/make_your_data_agent_searchable.rst

**Heading-style + indentation** (3 files)

  - guide/building_ai_scientists/mcp_name_shortening.rst — strip stray
    leading spaces from two section titles + downgrade unknown
    ``.. critical::`` to ``.. important::``
  - about/deployment.rst — remove rogue ``=========`` underline below
    numbered-list items that mis-led the parser into skipping heading
    levels
  - guide/make_your_data_agent_searchable.rst — extend four "title
    underline too short" underlines + convert four markdown ``` fences
    to RST literal blocks

**Misc directive / target fixes**

  - guide/python_guide.rst — replace nonexistent ``.. success::`` with
    a tip-styled ``.. admonition::``
  - guide/euhealth_tools_tutorial.rst — indent ``.. note::`` body so it
    is no longer an empty admonition
  - help/troubleshooting.rst — same fix + remove rogue ``=========``
    line that was being read as a section overline
  - tools/cellosaurus_tools.rst — wrap ``CVCL_`` in literal backticks
    so the trailing underscore stops triggering missing-target lookups
  - expand_tooluniverse/index.rst — promote two leading-space bullet
    lists to standalone lists so the indentation is correct
  - expand_tooluniverse/reference/architecture.rst — switch ``.. graphviz::``
    (extension not installed) to a plain ``.. code-block:: text``;
    the embedded content was Mermaid pseudo-code anyway
  - guide/tools.rst — strip leading space on a section title

* docs: clear all remaining content warnings (lists, headings, refs, grids)

Round-4 build cleanup. Builds now finish with 0 structural ERRORs and 0
content WARNINGs; the only remaining ~11 warnings are pre-existing autodoc
infrastructure noise (duplicate object index entries from autosummary, and
the ghost_tool / medrxiv_tool modules that genuinely fail to import) — none
are in hand-written documentation.

Fixes in this commit:

**sphinx-design grids** (python_guide.rst)

  Re-indent two ``.. grid::`` blocks whose first card + options used 1-space
  indentation (Sphinx silently dropped them → "parent of grid-item should be
  grid-row"). Also fix a ``.. button-ref::`` whose content was indented 1
  space, producing a broken ``:any:`` cross-reference, and point it at the
  absolute ``/api/modules``.

**Numbered/bulleted sub-lists** (tool_composition, literature_search ×2,
architecture, literature_search_web_ui, make_your_data, agentic_tools,
finding_tools, euhealth)

  Insert the required blank line before nested lists and re-indent 1-space
  sub-bullets to align under their parent list marker. Clears ~80
  "list ends without a blank line; unexpected unindent" warnings.

**Title underlines** (logging, tool_caller, loading_tools, tool_composition,
euhealth, make_your_data, contributing/local_tools, reference/index,
remote_tools/tutorial, troubleshooting + bulk pass)

  Extend underlines shorter than their title text; strip stray leading spaces
  from section titles that Sphinx read as block quotes.

**Stray markdown in RST** (make_your_data, local_tools)

  Convert leftover ``###`` headings and ``` ``` fences to proper RST
  directives; remove a rogue ``------`` separator that was being parsed as a
  section underline.

**Duplicate autosectionlabel** (make_your_data)

  Rename the second "How it works" heading to "How sharing works".

**uniprot_tools** (JSON + generated RST)

  Rephrase the ``min_length`` / ``max_length`` descriptions so the open-ended
  range syntax no longer contains a bare ``*`` that RST read as an unterminated
  emphasis marker. Fixed in the JSON source so it survives doc regeneration.
2026-05-30 22:34:05 -07:00

294 lines
8.8 KiB
Python
Raw Blame History

# Configuration file for Sphinx documentation with Shibuya theme.
# Modern, elegant theme with excellent sidebar navigation and i18n support
import os
import sys
sys.path.insert(0, os.path.abspath("../src"))
# -- Project information -----------------------------------------------------
project = "ToolUniverse"
copyright = "2025, Shanghua Gao"
author = "Shanghua Gao"
release = "1.0.0"
# -- General configuration ---------------------------------------------------
extensions = [
"sphinx.ext.autodoc",
"sphinx.ext.viewcode",
"sphinx.ext.napoleon",
"sphinx.ext.intersphinx",
"sphinx.ext.todo",
"sphinx.ext.coverage",
"sphinx.ext.mathjax",
"sphinx.ext.githubpages",
"sphinx.ext.autosummary",
"sphinx.ext.autosectionlabel",
"myst_parser",
"sphinx_copybutton",
"sphinx_tabs.tabs",
"sphinx_design",
# "notfound.extension", # Temporarily disabled due to theme compatibility issue
"sphinx_reredirects",
]
# HTML redirects for paths that moved during a docs reshuffle.
# Old path → new path. The ToolUniverse paper and external blog posts cite
# legacy URLs from before the docs were reorganised. Without these redirects
# every cited URL 404s. Each entry was verified against the live site:
# the destination must already return HTTP 200.
redirects = {
# /tutorials/* → /guide/*
"tutorials/tooluniverse_case_study": "../guide/tooluniverse_case_study.html",
"tutorials/agentic_tools_tutorial": "../guide/agentic_tools_tutorial.html",
"tutorials/literature_search_tools_tutorial": "../guide/literature_search_tools_tutorial.html",
"tutorials/literature_search_web_ui_tutorial": "../guide/literature_search_web_ui_tutorial.html",
"tutorials/visualization_tutorial": "../guide/visualization_tutorial.html",
"tutorials/expert_feedback": "../guide/expert_feedback.html",
"tutorials/finding_tools": "../guide/finding_tools.html",
"tutorials/make_your_data_searchable": "../guide/make_your_data_agent_searchable.html",
"tutorials/make_your_data_agent_searchable": "../guide/make_your_data_agent_searchable.html",
"tutorials/build_search_and_share_datastores": "../guide/make_your_data_agent_searchable.html",
"tutorials/skills": "../guide/skills_showcase.html",
"tutorials/tool_finder": "../guide/finding_tools.html",
"tutorials/overview": "../guide/index.html",
# /tutorials/* → /tools/* and /expand_tooluniverse/*
"tutorials/remote_tools": "../tools/remote_tools.html",
"tutorials/mcp_integration": "../expand_tooluniverse/remote_tools/mcp_integration.html",
# Top-level pages whose content moved into /about/ or /help/
"getting_started": "guide/python_guide.html",
"deployment": "about/deployment.html",
"contributing": "about/contributing.html",
"changelog": "about/changelog.html",
"faq": "help/faq.html",
}
templates_path = ["_templates"]
exclude_patterns = [
"_build",
"Thumbs.db",
".DS_Store",
"old_files",
"old",
"dev_docs",
"tutorials/aiscientists",
"translation_tools",
"tutorials/overview.md",
"tutorials/optimization",
"guide/ODPHPtools_tutorial.md",
# Internal meta-docs describing the folder structure or task list.
# Not user-facing; kept in-tree as a developer reference only.
"DOCUMENTATION_STRUCTURE.md",
]
# -- Options for HTML output with Shibuya theme -----------------------------
html_theme = "shibuya"
html_static_path = ["_static"]
# -- Shibuya theme configuration --------------------------------------------
html_theme_options = {
# Navigation
"nav_links": [
{
"title": "aiscientist.tools",
"url": "https://aiscientist.tools",
},
{
"title": "Home",
"url": "index",
},
{
"title": "AI Agents",
"url": "guide/building_ai_scientists/index",
},
{
"title": "Python",
"url": "guide/python_guide",
},
{
"title": "Tutorials",
"url": "guide/index",
},
{
"title": "Tools",
"url": "tools/tools_config_index",
},
],
# GitHub integration
"github_url": "https://github.com/mims-harvard/ToolUniverse",
# Design options
"page_layout": "default",
"color_mode": "auto", # auto, light, dark
"accent_color": "blue",
# Logo configuration
"light_logo": "_static/logo.png",
"dark_logo": "_static/logo.png",
# Sidebar configuration
"globaltoc_expand_depth": 2, # Expand 2 levels by default
"toctree_collapse": True, # Allow collapsing sections
"toctree_titles_only": False, # Show full navigation including children
"toctree_includehidden": True, # Include hidden toctrees in navigation
# Social links (disabled)
"twitter_site": "",
"twitter_creator": "",
"twitter_url": "",
"discord_url": "",
"discussion_url": "",
# Carbon ads (disabled)
"carbon_ads_code": "",
"carbon_ads_placement": "",
# Ethical ads (disabled)
"ethical_ads_publisher": "",
}
# HTML options
html_title = f"{project} Documentation"
html_short_title = project
html_logo = "_static/logo.png" if os.path.exists("_static/logo.png") else None
html_favicon = "_static/logo_transparent.png" if os.path.exists("_static/logo_transparent.png") else None
# Let Shibuya use its default sidebar layout
# Left sidebar: global navigation (from toctree, titles only)
# Right sidebar: page TOC (in-page sections) - handled automatically by Shibuya
# Custom CSS
html_css_files = [
"custom.css",
"language_switcher.css",
"custom_modern.css", # Modern interactive styles
]
# Custom JavaScript
html_js_files = [
"language_switcher.js",
"sidebar_control.js", # Custom per-section sidebar expansion control
]
# -- Autodoc configuration ---------------------------------------------------
autodoc_default_options = {
"members": True,
"member-order": "bysource",
"special-members": "__init__",
"undoc-members": True,
"exclude-members": "__weakref__",
"show-inheritance": True,
}
# Skip problematic modules that have import issues or blocking operations
autodoc_mock_imports = [
"flask_cors",
"tooluniverse.web_tools.literature_search_ui",
"tooluniverse.visualization_tool",
"tooluniverse.tool_graph_web_ui",
"tooluniverse.web_search_tool",
]
autodoc_typehints = "description"
autodoc_typehints_description_target = "documented"
autodoc_class_signature = "separated"
autodoc_member_order = "bysource"
# Napoleon settings
napoleon_google_docstring = True
napoleon_numpy_docstring = True
napoleon_include_init_with_doc = True
napoleon_include_private_with_doc = False
napoleon_include_special_with_doc = True
napoleon_use_admonition_for_examples = True
napoleon_use_admonition_for_notes = True
napoleon_use_admonition_for_references = True
napoleon_use_ivar = False
napoleon_use_param = True
napoleon_use_rtype = True
napoleon_preprocess_types = True
napoleon_type_aliases = None
napoleon_attr_annotations = True
# MyST Parser settings
myst_enable_extensions = [
"dollarmath",
"amsmath",
"deflist",
"html_admonition",
"html_image",
"colon_fence",
"attrs_inline",
"attrs_block",
# "linkify", # Disabled - requires linkify-it-py
]
# Todo extension settings
todo_include_todos = True
# Intersphinx mapping
intersphinx_mapping = {
"python": ("https://docs.python.org/3/", None),
"numpy": ("https://numpy.org/doc/stable/", None),
"requests": ("https://docs.python-requests.org/en/latest/", None),
}
# Sphinx-copybutton settings
copybutton_prompt_text = r">>> |\.\.\. |\$ |In \[\d*\]: | {2,5}\.\.\.: | {5,8}: "
copybutton_prompt_is_regexp = True
# Autosummary settings
autosummary_generate = True
autosummary_imported_members = True
# Autosectionlabel settings
autosectionlabel_prefix_document = True
autosectionlabel_maxdepth = 2 # Don't label deep sections in docstrings
# Source file suffixes
source_suffix = {
".rst": "restructuredtext",
".md": "markdown",
}
# Master document
master_doc = "index"
# HTML options
html_show_sourcelink = True
html_show_sphinx = False
html_show_copyright = True
# Language and search
language = "en"
html_search_language = "en"
# Syntax highlighting
pygments_style = "default"
pygments_dark_style = "monokai"
# -- Internationalization (i18n) support -------------------------------------
locale_dirs = ["locale/"]
gettext_compact = False
gettext_uuid = True
gettext_location = True
gettext_auto_build = True
# Supported languages for version switcher
languages = {
"en": "English",
"zh_CN": "简体中文",
}
# -- Enhanced setup function -------------------------------------------------
def setup(app):
"""Custom Sphinx setup function."""
app.add_css_file("custom.css")
return {
"version": "0.1",
"parallel_read_safe": True,
"parallel_write_safe": True,
}
Reference in New Issue View Git Blame Copy Permalink