Integrate documentation into main repository (#1388)

Author: nakamura-to

.readthedocs.yaml

@@ -0,0 +1,23 @@
+# .readthedocs.yaml
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Set the version of Python and other tools you might need
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.11"
+
+# Build documentation in the docs/ directory with Sphinx
+sphinx:
+  configuration: docs/conf.py
+  builder: dirhtml
+
+# We recommend specifying your dependencies to enable reproducible builds:
+# https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html
+python:
+  install:
+  - requirements: docs/requirements.txt

CLAUDE.md

@@ -80,6 +80,12 @@ SQL files use special comments for dynamic SQL that remain valid SQL when run di
 
 ## Development Guidelines
 
+### Setting Up Development Environment
+- Install JDK 21 (recommended via [SDKMAN](https://sdkman.io/jdks))
+- Clone repository: `git clone https://github.com/domaframework/doma.git`
+- Build project: `./gradlew build`
+- For IDE setup, import as a Gradle project (IntelliJ IDEA recommended)
+
 ### Annotation Processing Configuration
 When modifying annotation processors or entity/domain classes, the `ap` property in `gradle.properties` can be used to pass additional annotation processor options in CSV format.
 
@@ -93,8 +99,51 @@ All code must pass Spotless formatting checks. The build automatically applies f
 - Always use explicit imports for each class (e.g., `import java.util.List;`, `import java.util.Map;`)
 - This improves code readability and makes dependencies explicit
 
+### Contributing Guidelines
+- Submit contributions via GitHub Pull Requests from your own fork
+- Write issues and PRs in English for broader accessibility
+- All contributions are licensed under Apache License 2.0
+- Use snapshot versions from Sonatype repository for testing unreleased features
+
 ### Database Compatibility Testing
 When making changes that affect SQL generation or JDBC operations, run tests against multiple databases using `./gradlew testAll` to ensure compatibility.
 
 ### Integration Test Structure
 Integration tests use Testcontainers for database provisioning. Database URLs are configured in `gradle.properties` with the `TC_DAEMON=true` flag to improve test performance by reusing containers.
+
+## Documentation
+
+### Documentation System
+The project uses Sphinx for documentation generation, hosted on ReadTheDocs:
+- **Source**: Documentation source files are in the `docs/` directory
+- **Format**: Written in reStructuredText (`.rst`) format
+- **Languages**: English and Japanese (full translation support)
+- **URL**: https://doma.readthedocs.io/
+
+### Documentation Structure
+- **Getting Started**: Setup guide and quickstart (`getting-started.rst`)
+- **Core Concepts**: Entity, Domain, DAO, Embeddable documentation
+- **Query Operations**: Comprehensive guides for all database operations in `query/` subdirectory
+- **Query Building**: Criteria API, Query DSL, SQL templates documentation
+- **Framework Integration**: Spring Boot, Quarkus, Lombok, Kotlin support guides
+- **Development**: Build configuration, annotation processing, code generation
+
+### Building Documentation Locally
+```bash
+# Install dependencies
+cd docs
+pip install -r requirements.txt
+
+# Generate HTML documentation with auto-reload
+sphinx-autobuild . _build/html
+# Visit http://127.0.0.1:8000
+
+# Generate translation files
+sphinx-build -b gettext . _build/gettext
+```
+
+### Documentation Guidelines
+- Verify RST syntax and rendering before submitting PRs
+- Maintain consistency with existing documentation style
+- Update both English and Japanese translations when applicable
+- Test documentation builds locally using `sphinx-autobuild`

CONTRIBUTING.md

@@ -26,7 +26,7 @@ To contribute, use GitHub Pull Requests, from your own fork.
 Clone the repository and navigate to the root directory.
 Then run the Gradle `build` task:
 
-```
+```bash
 $ git clone https://github.com/domaframework/doma.git
 $ cd doma
 $ ./gradlew build
@@ -35,18 +35,43 @@ $ ./gradlew build
 #### Using snapshots
 
 Instead of building Doma from the master branch, you may want to use snapshots.
-To use snapshots, define a Maven repository in your build.gradle as follows:
+Snapshots are automatically published when each pull request is merged into the master branch.
+
+##### Gradle configuration
+
+Add the Sonatype snapshot repository to your `build.gradle.kts`:
 
-```groovy
+```kotlin
 repositories {
-    maven {url 'https://oss.sonatype.org/content/repositories/snapshots/'}
+    mavenCentral()
+    maven("https://central.sonatype.com/repository/maven-snapshots/")
+}
+```
+
+Then use the snapshot version (e.g., `3.10.0-SNAPSHOT`):
+
+```kotlin
+dependencies {
+    implementation("org.seasar.doma:doma-core:3.10.0-SNAPSHOT")
+    annotationProcessor("org.seasar.doma:doma-processor:3.10.0-SNAPSHOT")
 }
 ```
 
-Snapshots are published when each pull request is merged into the master branch.
-You can check the last publication date here:
+##### Maven configuration
+
+Add the repository to your `pom.xml`:
 
-- https://oss.sonatype.org/content/repositories/snapshots/org/seasar/doma/
+```xml
+<repositories>
+    <repository>
+        <id>sonatype-snapshots</id>
+        <url>https://central.sonatype.com/repository/maven-snapshots/</url>
+        <snapshots>
+            <enabled>true</enabled>
+        </snapshots>
+    </repository>
+</repositories>
+```
 
 ### IDE - IntelliJ IDEA
 
@@ -57,15 +82,101 @@ Import the root directory as a Gradle project.
 We use [spotless](https://github.com/diffplug/spotless) and
 [google-java-format](https://github.com/google/google-java-format) for code formatting.
 
-To format, just run the Gradle `build` task:
+#### Automatic formatting
 
-```
+Code formatting is automatically applied when running the build:
+
+```bash
 $ ./gradlew build
 ```
 
-To run google-java-format in your IDE,
-see https://github.com/google/google-java-format#using-the-formatter.
+To only check formatting without building:
+
+```bash
+$ ./gradlew spotlessCheck
+```
+
+To apply formatting without building:
+
+```bash
+$ ./gradlew spotlessApply
+```
+
+#### IDE integration
+
+To run google-java-format in your IDE:
+- IntelliJ IDEA: Install the [google-java-format plugin](https://plugins.jetbrains.com/plugin/8527-google-java-format)
+- Eclipse: Follow instructions at https://github.com/google/google-java-format#eclipse
+- VS Code: Install the [Language Support for Java extension](https://marketplace.visualstudio.com/items?itemName=redhat.java)
+
+**Important**: Do not use wildcard imports (e.g., `import java.util.*;`). Always use explicit imports.
 
 ### Documentation
 
-See https://github.com/domaframework/doma-docs
+We use [Sphinx](http://sphinx-doc.org) to generate documents.
+The generated documents are hosted on ReadTheDocs.
+
+- **Production**: https://doma.readthedocs.io/
+- **Latest (master branch)**: https://doma.readthedocs.io/en/latest/
+
+To contribute to documentation, you need Python 3.x.
+
+#### Install Sphinx
+
+Navigate to the docs directory and install dependencies:
+
+```bash
+$ cd docs
+$ pip install -r requirements.txt
+```
+
+#### Generate HTML files
+
+Use `sphinx-autobuild` for live-reloading development server:
+
+```bash
+$ cd docs
+$ sphinx-autobuild . _build/html
+```
+
+Visit http://127.0.0.1:8000 to preview your changes. The page automatically reloads when you modify RST files.
+
+#### Build documentation
+
+To build HTML documentation without auto-reload:
+
+```bash
+$ cd docs
+$ make html
+```
+
+The generated HTML files will be in `docs/_build/html/`.
+
+#### Translations
+
+Doma documentation supports Japanese translations. To work with translations:
+
+Generate POT files (translation templates):
+
+```bash
+$ cd docs
+$ sphinx-build -b gettext . _build/gettext
+```
+
+Update PO files (translation files):
+
+```bash
+$ cd docs
+$ sphinx-intl update -p _build/gettext -l ja
+```
+
+The Japanese translation files are located in `docs/locale/ja/LC_MESSAGES/`.
+
+#### Documentation guidelines
+
+- Write documentation in English first
+- Use clear, concise language
+- Include code examples where appropriate
+- Test all code examples to ensure they work
+- Verify RST syntax and rendering before submitting PRs
+- Update the table of contents (`index.rst`) when adding new pages

docs/.gitignore

@@ -0,0 +1,2 @@
+/_build/
+/locale/**/*.mo

docs/Makefile

@@ -0,0 +1,19 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line.
+SPHINXOPTS    =
+SPHINXBUILD   = sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)