Copilot commented on code in PR #446: URL: https://github.com/apache/incubator-hugegraph-doc/pull/446#discussion_r2749694310
########## AGENTS.md: ########## @@ -1,171 +1,110 @@ -# AI Development Agent Instructions +# AGENTS.md This file provides guidance to AI coding assistants (Claude Code, Cursor, GitHub Copilot, etc.) when working with code in this repository. ## Project Overview -This is the **Apache HugeGraph documentation website** repository (`hugegraph-doc`), built with Hugo static site generator using the Docsy theme. The site provides comprehensive documentation for the HugeGraph graph database system, including quickstart guides, API references, configuration guides, and contribution guidelines. +Apache HugeGraph documentation website built with Hugo static site generator and the Docsy theme. The site is bilingual (Chinese/English) and covers the complete HugeGraph graph database ecosystem. -The documentation is multilingual, supporting both **Chinese (cn)** and **English (en)** content. - -## Development Setup - -### Prerequisites - -1. **Hugo Extended** (v0.95.0 recommended, v0.102.3 used in CI) - - Must be the "extended" version (includes SASS/SCSS support) - - Download from: https://github.com/gohugoio/hugo/releases - - Install location: `/usr/bin` or `/usr/local/bin` - -2. **Node.js and npm** (v16+ as specified in CI) - -### Quick Start +## Development Commands ```bash -# Install npm dependencies (autoprefixer, postcss, postcss-cli) +# Install dependencies npm install -# Start local development server (with auto-reload) +# Start development server (auto-reload enabled) hugo server -# Custom server with different ip/port -hugo server -b http://127.0.0.1 -p 80 --bind=0.0.0.0 - # Build production site (output to ./public) hugo --minify -``` - -## Project Structure - -### Key Directories - -- **`content/`** - All documentation content in Markdown - - `content/cn/` - Chinese (simplified) documentation - - `content/en/` - English documentation - - Each language has parallel structure: `docs/`, `blog/`, `community/`, `about/` - -- **`themes/docsy/`** - The Docsy Hugo theme (submodule or vendored) - -- **`static/`** - Static assets (images, files) served directly - -- **`assets/`** - Assets processed by Hugo pipelines (SCSS, images for processing) - -- **`layouts/`** - Custom Hugo template overrides for the Docsy theme - -- **`public/`** - Generated site output (gitignored, created by `hugo` build) - -- **`dist/`** - Additional distribution files - -### Important Files - -- **`config.toml`** - Main site configuration - - Defines language settings (cn as default, en available) - - Menu structure and navigation - - Theme parameters and UI settings - - Currently shows version `0.13` - -- **`package.json`** - Node.js dependencies for CSS processing (postcss, autoprefixer) -- **`.editorconfig`** - Code style rules (UTF-8, LF line endings, spaces for indentation) +# Clean build +rm -rf public/ -- **`contribution.md`** - Contributing guide (Chinese/English mixed) +# Production build with garbage collection +HUGO_ENV="production" hugo --gc -- **`maturity.md`** - Project maturity assessment documentation +# Custom server configuration +hugo server -b http://127.0.0.1 -p 80 --bind=0.0.0.0 +``` -## Content Organization +## Prerequisites -Documentation is organized into major sections: +- **Hugo Extended** v0.95.0 recommended (v0.102.3 in CI) - must be the "extended" version for SASS/SCSS support +- **Node.js** v16+ and npm +- Download Hugo from: https://github.com/gohugoio/hugo/releases -- **`quickstart/`** - Getting started guides for HugeGraph components (Server, Loader, Hubble, Tools, Computer, AI) -- **`config/`** - Configuration documentation -- **`clients/`** - Client API documentation (Gremlin Console, RESTful API) -- **`guides/`** - User guides and tutorials -- **`performance/`** - Performance benchmarks and optimization -- **`language/`** - Query language documentation -- **`contribution-guidelines/`** - How to contribute to HugeGraph -- **`changelog/`** - Release notes and version history -- **`download/`** - Download links and instructions +## Architecture -## Common Tasks +``` +content/ +├── cn/ # Chinese documentation (default language) +│ ├── docs/ # Main documentation +│ ├── blog/ # Blog posts +│ ├── community/ +│ └── about/ +└── en/ # English documentation (parallel structure) + +themes/docsy/ # Docsy theme (submodule) +layouts/ # Custom template overrides +assets/ # Processed assets (SCSS, images) +static/ # Static files served directly +config.toml # Main site configuration +``` -### Building and Testing +### Content Structure -```bash -# Build for production (with minification) -hugo --minify +Documentation sections in `content/{cn,en}/docs/`: +- `quickstart/` - Getting started guides for HugeGraph components +- `config/` - Configuration documentation +- `clients/` - Client API documentation (Gremlin, RESTful) +- `guides/` - User guides and tutorials +- `performance/` - Benchmarks and optimization +- `language/` - Query language docs +- `contribution-guidelines/` - Contributing guides +- `changelog/` - Release notes +- `download/` - Download instructions -# Clean previous build -rm -rf public/ +## Key Configuration Files -# Build with specific environment -HUGO_ENV="production" hugo --gc -``` +- `config.toml` - Site-wide settings, language config, menu structure, version (currently 0.13) Review Comment: `config.toml` is now configured with `version = "1.7"`, but this note still states the version is "currently 0.13", which can mislead tooling or contributors relying on this guide. Please update the mentioned version here to match the actual value in `config.toml` so the documentation stays consistent. ```suggestion - `config.toml` - Site-wide settings, language config, menu structure, version (currently 1.7) ``` ########## content/cn/docs/quickstart/hugegraph/hugegraph-server.md: ########## @@ -138,11 +140,11 @@ mvn package -DskipTests HugeGraph-Tools 提供了一键部署的命令行工具，用户可以使用该工具快速地一键下载、解压、配置并启动 HugeGraph-Server 和 HugeGraph-Hubble，最新的 HugeGraph-Toolchain 中已经包含所有的这些工具，直接下载它解压就有工具包集合了 ```bash -# download toolchain package, it includes loader + tool + hubble, please check the latest version (here is 1.5.0) -wget https://downloads.apache.org/incubator/hugegraph/1.5.0/apache-hugegraph-toolchain-incubating-1.5.0.tar.gz +# download toolchain package, it includes loader + tool + hubble, please check the latest version (here is 1.7.0) +wget https://downloads.apache.org/incubator/hugegraph/1.7.0/apache-hugegraph-toolchain-incubating-1.7.0.tar.gz tar zxf *hugegraph-*.tar.gz # enter the tool's package -cd *hugegraph*/*tool* +cd *hugegraph*/*tool* Review Comment: The fenced code block inside this `<details>` section has mismatched ```bash fences: there is an extra opening ```bash before the `#### 3.4` heading and another ```bash before the download commands, which causes the heading to be rendered as code and can leave a code block unclosed. Please collapse this to a single fenced code block (e.g., move `#### 3.4` outside of the code block and keep only one ```bash fence around the shell commands) so the Markdown renders correctly. -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected] --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
