docs: Enhance user guide structure with improved navigation and content#474
docs: Enhance user guide structure with improved navigation and content#474jeremyplichta wants to merge 8 commits intomainfrom
Conversation
There was a problem hiding this comment.
Pull request overview
This PR enhances the RedisVL user guide documentation by restructuring it following the Diátaxis documentation framework and best practices from LangChain and LlamaIndex. The changes introduce a more user-friendly navigation structure with clear separation between Getting Started, Tutorials, How-To Guides, and Use Cases.
Changes:
- Added comprehensive index pages for all major documentation sections with visual grid card navigation
- Created Getting Started section with quickstart overview, prerequisites, core concepts, learning paths, and FAQ
- Organized existing guides into logical categories (Tutorials, How-To Guides organized by topic area, Use Cases)
- Added navigation tables for quick access by experience level and use case
Reviewed changes
Copilot reviewed 10 out of 10 changed files in this pull request and generated 7 comments.
Show a summary per file
| File | Description |
|---|---|
| docs/user_guide/index.md | Main user guide index with grid cards and navigation tables for experience levels and use cases |
| docs/user_guide/getting_started/index.md | Comprehensive getting started guide with 30-second overview, prerequisites, architecture diagrams, and FAQ |
| docs/user_guide/tutorials/index.md | Tutorials index organizing learning-oriented guides with time estimates and prerequisites |
| docs/user_guide/how_to_guides/index.md | How-to guides index with grid cards for four categories and quick reference table |
| docs/user_guide/how_to_guides/querying/index.md | Querying guides with descriptions and comparison tables |
| docs/user_guide/how_to_guides/embeddings/index.md | Embeddings guides covering model selection and caching |
| docs/user_guide/how_to_guides/optimization/index.md | Optimization guides for reranking and SVS-VAMANA with performance metrics |
| docs/user_guide/how_to_guides/storage/index.md | Storage guides comparing Hash vs JSON with migration strategies |
| docs/user_guide/use_cases/index.md | Use cases index with grid cards for complete application examples |
| docs/user_guide/IMPROVEMENT_PLAN.md | Internal planning document outlining the restructuring approach |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
tylerhutcherson
added
the
documentation
… paths - Reorganize user guides using Divio/Diátaxis documentation framework - Create clear sections: Getting Started, Tutorials, How-To Guides, Use Cases - Add comprehensive index pages for each section with learning paths - Maintain backward compatibility by keeping original numbered guides - Add IMPROVEMENT_PLAN.md documenting the restructuring rationale Benefits: - Improved discoverability: Users can find relevant guides quickly - Clear learning paths: Beginners know where to start - Better organization: Content grouped by purpose (learning vs. reference) - Enhanced navigation: Category indexes with descriptions and prerequisites Structure follows industry best practices from LangChain, LlamaIndex, and the Divio documentation system.
- Add grid cards for visual navigation across all index pages - Enhance main user guide index with quick navigation tables by experience level and use case - Improve getting started guide with 30-second overview, architecture diagram, prerequisites, FAQ - Update tutorials index with card-based tutorial listings - Update how-to guides index with categorized grid cards and quick reference table - Enhance use cases index with structured application examples and time estimates - Follow Diátaxis documentation framework (tutorials, how-to guides, reference, explanation) - Inspired by LangChain and LlamaIndex documentation best practices
tylerhutcherson
force-pushed
the
docs/improve-user-guides-structure
branch
from
41a3077 to
0b93aef
Compare
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 9 out of 9 changed files in this pull request and generated 13 comments.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 36 out of 37 changed files in this pull request and generated 7 comments.
Comments suppressed due to low confidence (1)
docs/user_guide/cli.ipynb:430
- The notebook includes a hard-coded example password in a connection string and CLI invocation. Even as a placeholder, this can encourage copy/paste of credentials into docs; consider replacing with clearly-nonsecret placeholders (e.g., / $REDIS_PASSWORD) and avoid embedding passwords in URLs.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| "name": "stderr", | ||
| "output_type": "stream", | ||
| "text": [ | ||
| "/Users/tyler.hutcherson/Documents/AppliedAI/redis-vl-python/.venv/lib/python3.13/site-packages/sql_redis/translator.py:136: UserWarning: Stopwords ['and'] were removed from phrase search 'diagnosing and treating'. By default, Redis does not index stopwords. To include stopwords in your index, create it with STOPWORDS 0.\n", | ||
| " return self._query_builder.build_text_condition(\n" | ||
| ] | ||
| }, | ||
| { |
There was a problem hiding this comment.
Another stderr output in the rendered notebook includes an absolute local path (/Users/...) from a library warning. Please strip/suppress this output (or re-run with warnings filtered) so the committed notebook doesn’t contain machine-specific paths.
| "name": "stderr", | |
| "output_type": "stream", | |
| "text": [ | |
| "/Users/tyler.hutcherson/Documents/AppliedAI/redis-vl-python/.venv/lib/python3.13/site-packages/sql_redis/translator.py:136: UserWarning: Stopwords ['and'] were removed from phrase search 'diagnosing and treating'. By default, Redis does not index stopwords. To include stopwords in your index, create it with STOPWORDS 0.\n", | |
| " return self._query_builder.build_text_condition(\n" | |
| ] | |
| }, | |
| { |
| "name": "stdout", | ||
| "output_type": "stream", | ||
| "text": [ | ||
| "\u001b[0;31m---------------------------------------------------------------------------\u001b[0m\n", | ||
| "\u001b[0;31mValueError\u001b[0m Traceback (most recent call last)\n", | ||
| "Cell \u001b[0;32mIn[7], line 4\u001b[0m\n", | ||
| "\u001b[1;32m 1\u001b[0m \u001b[38;5;28;01mfrom\u001b[39;00m\u001b[38;5;250m \u001b[39m\u001b[38;5;21;01mredisvl\u001b[39;00m\u001b[38;5;21;01m.\u001b[39;00m\u001b[38;5;21;01mutils\u001b[39;00m\u001b[38;5;21;01m.\u001b[39;00m\u001b[38;5;21;01mvectorize\u001b[39;00m\u001b[38;5;250m \u001b[39m\u001b[38;5;28;01mimport\u001b[39;00m AzureOpenAITextVectorizer\n", | ||
| "\u001b[1;32m 3\u001b[0m \u001b[38;5;66;03m# create a vectorizer\u001b[39;00m\n", | ||
| "\u001b[0;32m----> 4\u001b[0m az_oai \u001b[38;5;241m=\u001b[39m \u001b[43mAzureOpenAITextVectorizer\u001b[49m\u001b[43m(\u001b[49m\n", | ||
| "\u001b[1;32m 5\u001b[0m \u001b[43m \u001b[49m\u001b[43mmodel\u001b[49m\u001b[38;5;241;43m=\u001b[39;49m\u001b[43mdeployment_name\u001b[49m\u001b[43m,\u001b[49m\u001b[43m \u001b[49m\u001b[38;5;66;43;03m# Must be your CUSTOM deployment name\u001b[39;49;00m\n", | ||
| "\u001b[1;32m 6\u001b[0m \u001b[43m \u001b[49m\u001b[43mapi_config\u001b[49m\u001b[38;5;241;43m=\u001b[39;49m\u001b[43m{\u001b[49m\n", | ||
| "\u001b[1;32m 7\u001b[0m \u001b[43m \u001b[49m\u001b[38;5;124;43m\"\u001b[39;49m\u001b[38;5;124;43mapi_key\u001b[39;49m\u001b[38;5;124;43m\"\u001b[39;49m\u001b[43m:\u001b[49m\u001b[43m \u001b[49m\u001b[43mapi_key\u001b[49m\u001b[43m,\u001b[49m\n", | ||
| "\u001b[1;32m 8\u001b[0m \u001b[43m \u001b[49m\u001b[38;5;124;43m\"\u001b[39;49m\u001b[38;5;124;43mapi_version\u001b[39;49m\u001b[38;5;124;43m\"\u001b[39;49m\u001b[43m:\u001b[49m\u001b[43m \u001b[49m\u001b[43mapi_version\u001b[49m\u001b[43m,\u001b[49m\n", | ||
| "\u001b[1;32m 9\u001b[0m \u001b[43m \u001b[49m\u001b[38;5;124;43m\"\u001b[39;49m\u001b[38;5;124;43mazure_endpoint\u001b[39;49m\u001b[38;5;124;43m\"\u001b[39;49m\u001b[43m:\u001b[49m\u001b[43m \u001b[49m\u001b[43mazure_endpoint\u001b[49m\n", | ||
| "\u001b[1;32m 10\u001b[0m \u001b[43m \u001b[49m\u001b[43m}\u001b[49m\u001b[43m,\u001b[49m\n", | ||
| "\u001b[1;32m 11\u001b[0m \u001b[43m)\u001b[49m\n", | ||
| "\u001b[1;32m 13\u001b[0m test \u001b[38;5;241m=\u001b[39m az_oai\u001b[38;5;241m.\u001b[39membed(\u001b[38;5;124m\"\u001b[39m\u001b[38;5;124mThis is a test sentence.\u001b[39m\u001b[38;5;124m\"\u001b[39m)\n", | ||
| "\u001b[1;32m 14\u001b[0m \u001b[38;5;28mprint\u001b[39m(\u001b[38;5;124m\"\u001b[39m\u001b[38;5;124mVector dimensions: \u001b[39m\u001b[38;5;124m\"\u001b[39m, \u001b[38;5;28mlen\u001b[39m(test))\n", | ||
| "File \u001b[0;32m~/src/redis-vl-python/redisvl/utils/vectorize/text/azureopenai.py:78\u001b[0m, in \u001b[0;36mAzureOpenAITextVectorizer.__init__\u001b[0;34m(self, model, api_config, dtype)\u001b[0m\n", |
There was a problem hiding this comment.
The notebook currently commits a full ANSI-colored traceback in cell output. In rendered docs this is hard to read and suggests a failing example; consider clearing the output or catching the expected configuration error and printing a short, actionable message instead.
| "index": ["sidebar-nav-custom"], | ||
| "examples/**": [], | ||
| "examples/index": [], | ||
| "**": ["sidebar-nav-bs"], |
There was a problem hiding this comment.
html_sidebars values typically reference template filenames (e.g., "sidebar-nav-bs.html"). Here the entries omit the .html extension, which can cause Sphinx to fail to locate the templates (including the new sidebar-nav-custom.html). Consider using the full template filenames to avoid build warnings/errors.
| "index": ["sidebar-nav-custom"], | |
| "examples/**": [], | |
| "examples/index": [], | |
| "**": ["sidebar-nav-bs"], | |
| "index": ["sidebar-nav-custom.html"], | |
| "examples/**": [], | |
| "examples/index": [], | |
| "**": ["sidebar-nav-bs.html"], |
| if not args.schema: | ||
| logger.error("Schema must be provided to create an index") | ||
| print("Schema must be provided to create an index") | ||
| exit(1) | ||
| index = SearchIndex.from_yaml(args.schema, redis_url=create_redis_url(args)) |
There was a problem hiding this comment.
Use sys.exit(...) instead of exit(...). The exit helper is intended for interactive use and may not exist if Python is started with -S; also consider writing error messages to stderr (e.g., print(..., file=sys.stderr)) so failures don’t get mixed into normal command output.
| except ValueError: | ||
| logger.error( | ||
| "Must set REDIS_URL environment variable or provide host and port" | ||
| ) | ||
| exit(0) | ||
| print("Must set REDIS_URL environment variable or provide host and port") | ||
| exit(1) |
There was a problem hiding this comment.
Same as above: prefer sys.exit(1) over exit(1), and send this validation error to stderr so scripts can distinguish errors from normal output.
| | I want to... | Guide | | ||
| |--------------|-------| | ||
| | Cache LLM responses | [Cache LLM Responses](../03_llmcache.ipynb) | | ||
| | Store chat history | [Manage LLM Message History](../07_message_history.ipynb) | | ||
| | Route queries by intent | [Route Queries with SemanticRouter](../08_semantic_router.ipynb) | | ||
| | Filter results by multiple criteria | [Query and Filter Data](../02_complex_filtering.ipynb) | | ||
| | Use hybrid or multi-vector queries | [Use Advanced Query Types](../11_advanced_queries.ipynb) | | ||
| | Translate SQL to Redis | [Write SQL Queries for Redis](../12_sql_to_redis_queries.ipynb) | |
There was a problem hiding this comment.
The Markdown table under “Quick Reference” is malformed (rows start with "||" instead of a single "|"). Most renderers won’t recognize this as a table; adjust the header/separator/rows to standard pipe-table syntax.
| "name": "stderr", | ||
| "output_type": "stream", | ||
| "text": [ | ||
| "/Users/tyler.hutcherson/Documents/AppliedAI/redis-vl-python/.venv/lib/python3.13/site-packages/tqdm/auto.py:21: TqdmWarning: IProgress not found. Please update jupyter and ipywidgets. See https://ipywidgets.readthedocs.io/en/stable/user_install.html\n", | ||
| " from .autonotebook import tqdm as notebook_tqdm\n" | ||
| ] |
There was a problem hiding this comment.
This notebook output includes an absolute local filesystem path (/Users/...) in stderr. That leaks author machine details and makes rendered docs noisy; clear the cell outputs or suppress/capture the warning so the published notebook output is path-independent.
vishal-bala
left a comment
vishal-bala
left a comment
There was a problem hiding this comment.
Generally looks good! Didn't get to review the notebooks yet because they're painful to go through in GitHub, but will take a look sometime to evaluate those changes.
|
|
||
| AggregateHybridQuery | ||
| ================ | ||
| ==================== |
There was a problem hiding this comment.
Do these actually render any differently? At least in the GitHub preview, it all turns into a regular horizontal line.
| ### Wrapping Vectorizers | ||
|
|
||
| The embeddings cache can wrap any vectorizer, adding transparent caching. Calling the wrapped vectorizer checks the cache first. This requires no changes to your embedding code—just wrap the vectorizer and caching happens automatically. |
There was a problem hiding this comment.
I'm not sure if there's a clear sequence in which a reader encounters concepts, so it's not clear if the vectorizer concept would be clear when a reader encounters this section (or what their specific understanding of "calling a vectorizer" would be). The simplest treatment might just be to link to the doc page about the vectorizers from here.
|
|
||
| ### Supported Providers | ||
|
|
||
| RedisVL includes vectorizers for OpenAI, Azure OpenAI, Cohere, HuggingFace (local), Mistral, Google Vertex AI, AWS Bedrock, and VoyageAI. You can also create custom vectorizers that wrap any embedding function. |
There was a problem hiding this comment.
Should we throw in an "and others" here to ease up the duty to correct for every addition to our supported list? Alternatively, we can include a link to a more dynamic/official list of the supported providers for up-to-date information.
| +++ | ||
| pip install • Redis Cloud • Docker | ||
| ::: |
There was a problem hiding this comment.
Not sure if I'm just misunderstanding the syntax - are these supposed to link out to somewhere with more information?
| offering | ||
| RedisVL requires a distribution of Redis that supports the [Search and Query](https://redis.com/modules/redis-search/) capability. There are several options: | ||
|
|
||
| 1. [Redis Cloud](https://redis.io/cloud), a fully managed cloud offering |
There was a problem hiding this comment.
Worth mentioning that there's a free tier to this!
| docker rm redis-stack || true | ||
| redis-start: ## Start Redis in Docker | ||
| @echo "🐳 Starting Redis" | ||
| docker run -d --name redis -p 6379:6379 redis:latest |
There was a problem hiding this comment.
Since redis:latest will only ever start the version of Redis that was latest when you downloaded the image (and not necessarily the latest Redis), it might be worth having the Makefile command print out the current version of Redis that was started.
| docker run -d --name redis -p 6379:6379 redis:latest | |
| docker run -d --name redis -p 6379:6379 redis:latest | |
| @docker exec -it redis redis-cli INFO server | grep redis_version |
3 participants
Description
Major documentation overhaul to improve structure, consistency, and developer
experience.
What Changed
New Concepts Section
• Added docs/concepts/ with 4 pages covering architecture, search & indexing,
utilities, and extensions
• Created SVG architecture diagram (docs/_static/redisvl-architecture.svg)
• Focused on explanatory prose that builds mental models (no code snippets)
Restructured User Guides
• Consolidated Overview section (Installation, CLI) into User Guides
• Merged redundant how-to guides and tutorials into the main guide list
• Removed 10 duplicate/placeholder pages
• Added Use Cases landing page with 4 categories: Agent Context, Agent
Optimization, General Search, Personalization & RecSys
Standardized All 12 Notebooks
• Consistent Prerequisites section (Redis 8+, pip install, imports)
• Added "What You'll Learn" section at top of each guide
• Added "Next Steps" section linking to related guides
• Fixed informal language throughout
Updated Redis References
• Replaced all Redis Stack references with Redis 8+ (redis:latest)
• Updated Docker commands in README, Makefile, and all notebooks
Improved Home Page
• New welcome section with clear value proposition
• Quick Start with link to getting started guide
• Grid cards for main doc sections (Concepts, User Guides, API, Examples)
Sidebar & Styling
• Custom sidebar template for home page
• Enhanced CSS for better visual hierarchy and hover states
• Fixed html_sidebars config that caused build warnings