docs: Reduce README duplication with GitHub Pages site#1397
docs: Reduce README duplication with GitHub Pages site#1397anik120 wants to merge 1 commit intolightspeed-core:mainfrom
Conversation
WalkthroughThe README was restructured and rebranded from "lightspeed-stack" to "Lightspeed Core Stack (LCS)". Extensive implementation details including architecture diagrams, installation instructions, configuration sections, endpoint descriptions, database schema, and development tooling documentation were removed and replaced with condensed quick-start guidance and external documentation references. Changes
Estimated code review effort🎯 2 (Simple) | ⏱️ ~10 minutes 🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
🧹 Nitpick comments (1)
README.md (1)
65-80: Consider adding one explicit dev-tag example alongside:latest.You mention both stable and development images, but only show
:latest. Including one concrete dev tag example would make this section self-consistent.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@README.md` around lines 65 - 80, The Container Images section currently shows only the :latest tag; add a concrete development image example (e.g., :dev or :unstable) alongside the stable example by inserting a second pair of commands mirroring the existing podman pull and podman run lines but using a dev tag (for example quay.io/lightspeed-core/lightspeed-stack:dev) and a short label/comment indicating it is the development image so readers see both stable and dev usage; update the prose to mention the dev tag example in the same paragraph that references stable and development images.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@README.md`:
- Line 49: Update the Quick Start instruction that currently shows the
macOS-only "open http://localhost:8080/" so it works cross-platform: document
both macOS and Linux variants (e.g., "open http://localhost:8080/" for macOS and
"xdg-open http://localhost:8080/" for Linux) and suggest a cross-platform
alternative such as "python3 -m webbrowser http://localhost:8080/" so users on
different platforms can open the URL successfully.
- Around line 74-76: Update the example Podman/Docker run command in the README
so the host config file is mounted as a local file instead of a named volume;
replace the source volume "my-lightspeed-stack-config.yaml" with an explicit
relative or absolute path (e.g. "./my-lightspeed-stack-config.yaml" or
"/full/path/my-lightspeed-stack-config.yaml") in the command string "podman run
-it -p 8080:8080 -v ...:/app-root/lightspeed-stack.yaml:Z
quay.io/lightspeed-core/lightspeed-stack:latest" so users' local file is
correctly bind-mounted.
---
Nitpick comments:
In `@README.md`:
- Around line 65-80: The Container Images section currently shows only the
:latest tag; add a concrete development image example (e.g., :dev or :unstable)
alongside the stable example by inserting a second pair of commands mirroring
the existing podman pull and podman run lines but using a dev tag (for example
quay.io/lightspeed-core/lightspeed-stack:dev) and a short label/comment
indicating it is the development image so readers see both stable and dev usage;
update the prose to mention the dev tag example in the same paragraph that
references stable and development images.
README.md
Outdated
| # Start both services | ||
| docker compose up --build | ||
| # 6. Access the web UI | ||
| open http://localhost:8080/ |
There was a problem hiding this comment.
🧩 Analysis chain
🌐 Web query:
Is the open command available by default on Linux shells, and what is the standard cross-platform alternative to open URLs from terminal on Linux vs macOS?
💡 Result:
No, the open command is not available by default on Linux shells. It is a macOS-specific command that opens files, directories, or URLs in the default application. On Linux, the standard equivalent is xdg-open, part of the xdg-utils package, which is typically pre-installed on major distributions with desktop environments (e.g., GNOME, KDE). It opens files or URLs (like http/https) in the preferred application, such as the default web browser for URLs. For opening URLs from the terminal: - Linux: xdg-open - macOS: open There is no single built-in cross-platform command across Linux and macOS shells, but scripts can detect the OS and alias open to xdg-open on Linux (common practice). Python's python3 -m webbrowser works cross-platform without dependencies.
Citations:
- 1: https://superuser.com/questions/38984/linux-equivalent-command-for-open-command-on-mac-windows
- 2: https://unix.stackexchange.com/questions/124811/is-there-an-open-with-command-for-the-command-line
- 3: https://stackoverflow.com/questions/264395/linux-equivalent-of-the-mac-os-x-open-command
- 4: https://manpages.ubuntu.com/manpages/oracular/man1/xdg-open.1.html
- 5: https://stackoverflow.com/questions/5116473/linux-command-to-open-url-in-default-browser
Document platform-specific commands for opening URLs in Quick Start.
The open command is macOS-specific and will fail on Linux systems. Use xdg-open on Linux and open on macOS. Consider showing both variants in the instructions, or use a cross-platform alternative like python3 -m webbrowser http://localhost:8080/.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@README.md` at line 49, Update the Quick Start instruction that currently
shows the macOS-only "open http://localhost:8080/" so it works cross-platform:
document both macOS and Linux variants (e.g., "open http://localhost:8080/" for
macOS and "xdg-open http://localhost:8080/" for Linux) and suggest a
cross-platform alternative such as "python3 -m webbrowser
http://localhost:8080/" so users on different platforms can open the URL
successfully.
Streamlines the main README.md to serve as a landing page and portal to the github pages documentation site, eliminating 1,200+ lines of duplicated content. The root README.md contained comprehensive documentation (1,411 lines) that duplicated content already published in the `docs/` folder on GitHub Pages. This created two sources of truth: - https://github.com/lightspeed-core/lightspeed-stack/blob/main/README.md - https://lightspeed-core.github.io/lightspeed-stack/ This duplication risks divergence when documentation is updated in one place but not the other. This PR updates the README to be a landing page that directs to the documentation site, creating a single source of truth. Additionally, it bubbles up the github pages so that users can find it easily. Note: This reduces the README from ~1400 lines to ~150 lines, which is much easier to cosume since it is a "bite sized" piece now. Signed-off-by: Anik Bhattacharjee <anbhatta@redhat.com>
There was a problem hiding this comment.
🧹 Nitpick comments (1)
README.md (1)
76-78: Consider showing environment variable passing in the container example.The Quick Start section (line 40) demonstrates setting
OPENAI_API_KEYfor local development, but the containerized run command doesn't show how to pass environment variables. Users may not realize they need to add-e OPENAI_API_KEY=$OPENAI_API_KEYor similar flags.💡 Example with environment variable
# Run with your configuration podman run -it -p 8080:8080 \ + -e OPENAI_API_KEY \ -v ./lightspeed-stack.yaml:/app-root/lightspeed-stack.yaml:Z \ quay.io/lightspeed-core/lightspeed-stack:latestOr point users to the Deployment Guide earlier:
# Run with your configuration +# (See Deployment Guide for environment variables and full configuration) podman run -it -p 8080:8080 \🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@README.md` around lines 76 - 78, Update the podman run example to show how to pass environment variables by adding an -e flag for required keys (e.g., OPENAI_API_KEY) alongside the existing volume and port flags used in the podman run command that references lightspeed-stack.yaml and quay.io/lightspeed-core/lightspeed-stack:latest; alternatively, add a short sentence pointing readers to the Deployment Guide for environment variable and secret management if you prefer not to include the -e example inline.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Nitpick comments:
In `@README.md`:
- Around line 76-78: Update the podman run example to show how to pass
environment variables by adding an -e flag for required keys (e.g.,
OPENAI_API_KEY) alongside the existing volume and port flags used in the podman
run command that references lightspeed-stack.yaml and
quay.io/lightspeed-core/lightspeed-stack:latest; alternatively, add a short
sentence pointing readers to the Deployment Guide for environment variable and
secret management if you prefer not to include the -e example inline.
1 participant
Description
Streamlines the main README.md to serve as a landing page and portal to the github pages documentation site, eliminating 1,200+ lines of duplicated content.
The root README.md contained comprehensive documentation (1,411 lines) that duplicated content already published in the
docs/folder on GitHub Pages. This created two sources of truth:This duplication risks divergence when documentation is updated in one place but not the other.
This PR updates the README to be a landing page that directs to the documentation site, creating a single source of truth.
Additionally, it bubbles up the github pages so that users can find it easily.
Note: This reduces the README from ~1400 lines to ~150 lines, which is much easier to cosume since it is a "bite sized" piece now.
Type of change
Tools used to create PR
Identify any AI code assistants used in this PR (for transparency and review context)
Related Tickets & Documents
Checklist before requesting a review
Testing
Summary by CodeRabbit