Add GitHub Pages with documentation (#1100)

Closes #974.
Closes #1109.

.gitattributes

@@ -0,0 +1,3 @@
+*.png filter=lfs diff=lfs merge=lfs -text
+*.jpg filter=lfs diff=lfs merge=lfs -text
+*.jpeg filter=lfs diff=lfs merge=lfs -text

.github/dependabot.yml

@@ -8,6 +8,7 @@ updates:
       interval: "weekly"
       day: "thursday"
       time: "01:42"
+
   - package-ecosystem: "docker"
     directory: "/"
     labels: [deps]
@@ -22,6 +23,21 @@ updates:
       interval: "weekly"
       day: "thursday"
       time: "01:42"
+  - package-ecosystem: "docker"
+    directory: "/build/deps/textlint"
+    labels: [deps]
+    schedule:
+      interval: "weekly"
+      day: "thursday"
+      time: "01:42"
+  - package-ecosystem: "docker"
+    directory: "/website"
+    labels: [deps]
+    schedule:
+      interval: "weekly"
+      day: "thursday"
+      time: "01:42"
+
   - package-ecosystem: "gomod"
     directory: "/"
     labels: [deps]
@@ -43,3 +59,20 @@ updates:
       interval: "weekly"
       day: "thursday"
       time: "01:42"
+
+  - package-ecosystem: "npm"
+    directory: "/build/deps/textlint"
+    labels: [deps]
+    schedule:
+      interval: "weekly"
+      day: "thursday"
+      time: "01:42"
+  - package-ecosystem: "npm"
+    directory: "/website"
+    labels: [deps]
+    schedule:
+      interval: "weekly"
+      day: "thursday"
+      time: "01:42"
+    allow:
+      - dependency-name: "@docusaurus/*"

.github/workflows/docs.yml

@@ -21,7 +21,7 @@ env:
   GOPROXY: https://proxy.golang.org
 
 jobs:
-  docs:
+  build:
     name: Build docs
     runs-on: ubuntu-20.04
 
@@ -31,7 +31,7 @@ jobs:
       - name: Checkout code
         uses: actions/checkout@v3
         with:
-          fetch-depth: 0
+          lfs: true
 
       - name: Setup Go
         uses: FerretDB/github-actions/setup-go@main
@@ -48,7 +48,45 @@ jobs:
       - name: Build docs
         run: bin/task docs
 
+      - name: Archive docs
+        run: |
+          tar --directory website/build \
+            --file docs.tar \
+            --create \
+            --verbose \
+            .
+
+      - name: Upload archive artifact
+        uses: actions/upload-artifact@v3
+        with:
+          name: docs
+          path: docs.tar
+          if-no-files-found: error
+
       - name: Check dirty
         run: |
           git status
           git diff --exit-code
+
+  pages:
+    name: Deploy to Pages
+    runs-on: ubuntu-20.04
+
+    needs: build
+    if: github.event_name == 'push'
+
+    permissions:
+      pages: write
+      id-token: write
+
+    environment:
+      name: docs
+      url: ${{ steps.deploy.outputs.page_url }}
+
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deploy
+        uses: actions/deploy-pages@v1
+        with:
+          artifact_name: docs
+          timeout: 300000 # 5*60*1000 milliseconds

.github/workflows/go.yml

@@ -232,6 +232,8 @@ jobs:
         with:
           name: linux-logs
           path: /tmp/logs
+          retention-days: 14
+          if-no-files-found: error
 
       # we don't want them on CI
       - name: Clean test and fuzz caches

.github/workflows/packages.yml

@@ -55,11 +55,13 @@ jobs:
         with:
           name: ferretdb.deb
           path: build/deb/ferretdb.deb
+          retention-days: 14
           if-no-files-found: error
 
       - name: Upload ferretdb.rpm
         uses: actions/upload-artifact@v3
         with:
           name: ferretdb.rpm
           path: build/rpm/ferretdb.rpm
+          retention-days: 14
           if-no-files-found: error

.gitignore

@@ -1,25 +1,24 @@
 # Please use global .gitignore file for .vscode/, .idea/, etc.
 # See https://docs.github.com/en/get-started/getting-started-with-git/ignoring-files#configuring-ignored-files-for-all-repositories-on-your-computer
 
-# out tools
+# our tools
 bin/
 
-# temporary `go mod vendor` directory
+# dependencies
 vendor/
+node_modules/
 
 # task cache
 .task/
 
-# packages
+# packages, build artifacts
 *.deb
 *.rpm
+*.tar
 
 # test coverage results, generated files like commit.txt, etc.
 *.txt
 
-# test coverage results
-*.html
-
 # for now
 testdata/fuzz/
 

.textlintignore

@@ -1 +1,2 @@
 CHANGELOG.md
+website/node_modules/

CONTRIBUTING.md

@@ -14,24 +14,27 @@ or someone is already working on it.
 
 You can find a list of good issues for first-time contributors [there](https://github.com/FerretDB/FerretDB/contribute).
 
-## Contributing code
+## Setting up the environment
+
+### Requirements
 
-The supported way of developing FerretDB is to modify and run it on the host (Linux, macOS, or Windows)
+The supported way of contributing to FerretDB is to modify and run it on the host (Linux, macOS, or Windows)
 with PostgreSQL and other dependencies running inside Docker containers via Docker Compose.
 On Linux, `docker` and `docker-compose` should be installed on the host.
 On macOS and Windows, [Docker Desktop](https://www.docker.com/products/docker-desktop/) should be used.
 On Windows, it should be [configured to use WSL 2](https://docs.docker.com/desktop/windows/wsl/) without any distro;
 all commands should be run on the host.
 
-You will need Go 1.18 or later as FerretDB extensively uses ([fuzzing](https://go.dev/doc/tutorial/fuzz))
-and [generics](https://go.dev/doc/tutorial/generics)).
+You will need Go 1.18 or later on the host.
 If your package manager doesn't provide it yet,
 please install it from [go.dev](https://go.dev/dl/).
 
 You will also need `git` installed; the version provided by your package manager should do.
 On Windows, the simplest way to install it might be <https://gitforwindows.org>.
 
-### Cloning the Repository
+Finally, you will also need [git-lfs](https://git-lfs.github.com) installed and configured (`git lfs install`).
+
+### Making a working copy
 
 After [forking FerretDB on GitHub](https://github.com/FerretDB/FerretDB/fork),
 you can clone the repository:
@@ -42,8 +45,6 @@ cd FerretDB
 git remote add upstream https://github.com/FerretDB/FerretDB.git
 ```
 
-### Setting up the development environment
-
 To run development commands, you should first install the [`task`](https://taskfile.dev/) tool.
 You can do this by changing the directory to `tools` (`cd tools`) and running `go generate -x`.
 That will install `task` into the `bin` directory (`bin/task` on Linux and macOS, `bin\task.exe` on Windows).
@@ -53,23 +54,29 @@ or replace every invocation of `task` with explicit `bin/task`.
 You can also [install `task` globally](https://taskfile.dev/#/installation),
 but that might lead to the version skew.
 
-With `task` installed, you may do the following:
+With `task` installed,
+you should install development tools with `task init`
+and download required Docker images with `task env-pull`.
+
+You can see all available `task` tasks with `task -l`.
+
+## Contributing code
+
+### Commands for contributing code
 
-1. Install development tools with `task init`.
-2. Download required Docker images with `task env-pull`.
-3. Start the development environment with `task env-up`.
-4. Run all tests in another terminal window with `task test`.
-5. Start FerretDB with `task run`.
+With `task` installed (see above), you may do the following:
+
+1. Start the development environment with `task env-up`.
+2. Run all tests in another terminal window with `task test`.
+3. Start FerretDB with `task run`.
    This will start it in a development mode where all requests are handled by FerretDB, but also routed to MongoDB.
    The differences in response are then logged and the FerretDB response is sent back to the client.
-6. Fill `values` collection in `test` database with data for experiments with `task env-data`.
-7. Run `mongosh` with `task mongosh`.
+4. Fill `values` collection in `test` database with data for experiments with `task env-data`.
+5. Run `mongosh` with `task mongosh`.
    This allows you to run commands against FerretDB.
    For example, you can see what data was inserted by the previous command with `db.values.find()`.
 
-You can see all available `task` tasks with `task -l`.
-
-### Code Overview
+### Code overview
 
 The directory `cmd` provides commands implementation.
 Its subdirectory `ferretdb` is the main FerretDB binary; others are tools for development.
@@ -161,4 +168,16 @@ Before submitting a pull request, please make sure that:
 
 ## Contributing documentation
 
-Please format and lint documentation with `task docs`.
+### Commands for contributing documentation
+
+With `task` installed (see above), you may do the following:
+
+1. Format and lint documentation with `task docs-fmt`.
+2. Start Docusaurus development server with `task docs-dev`.
+3. Build Docusaurus website with `task docs`.
+
+### Submitting documentation changes
+
+Before submitting a pull request, please make sure that:
+
+1. Documentation is formatted, linted, and built with `task docs`.

README.md

@@ -44,8 +44,6 @@ and [contributing guidelines](CONTRIBUTING.md).
 
 If you encounter some other difference in behavior, please [join our community](#community) to report a problem.
 
-See also [docs/diff.md](docs/diff.md) for additional examples.
-
 ## Quickstart
 
 These steps describe a quick local setup.

Taskfile.yml

@@ -242,12 +242,6 @@ tasks:
       - bin/task{{exeExt}} -d integration lint-go-consistent
       - bin/task{{exeExt}} -d tools lint-go-consistent
 
-  docs:
-    desc: "Format and lint documentation"
-    cmds:
-      - docker-compose run --rm markdownlint --fix --dot --ignore CHANGELOG.md '**/*.md'
-      - docker-compose run --rm textlint --fix --rule one-sentence-per-line '**/*.md'
-
   godocs:
     desc: "Serve godoc documentation at http://127.0.0.1:6060/pkg/github.com/FerretDB/FerretDB/?m=all"
     cmds:
@@ -339,3 +333,20 @@ tasks:
         sh: cat ../internal/util/version/gen/version.txt
       GOARCH:
         sh: go env GOARCH
+
+  docs:
+    desc: "Format, lint and build documentation"
+    deps: [docs-fmt]
+    cmds:
+      - docker-compose run --rm docusaurus build
+
+  docs-fmt:
+    desc: "Format and lint documentation"
+    cmds:
+      - docker-compose run --rm markdownlint --fix --dot --ignore-path=.textlintignore '**/*.md'
+      - docker-compose run --rm textlint --fix --rule one-sentence-per-line '**/*.md'
+
+  docs-dev:
+    desc: "Start documentation development server"
+    cmds:
+      - docker-compose run --rm --service-ports docusaurus start --host=0.0.0.0

build/deps/textlint/Dockerfile

@@ -1,11 +1,8 @@
 FROM node:16.17.0-alpine3.16
 
-WORKDIR /tool
+WORKDIR /workdir/build/deps/textlint
 COPY . .
-
 RUN npm ci
-RUN ln -vs /tool/node_modules/.bin/* /usr/local/bin
 
-WORKDIR /workdir
-ENTRYPOINT ["textlint"]
+ENTRYPOINT ["/workdir/build/deps/textlint/node_modules/.bin/textlint"]
 CMD ["-h"]

build/deps/textlint/package.json

@@ -1,5 +1,5 @@
 {
-  "name": "tool",
+  "name": "tools",
   "dependencies": {
     "textlint": "12.2.1",
     "textlint-rule-one-sentence-per-line": "2.0.0"