docs: ドキュメントサイトの基礎 必要なツールの数を絞るために Nix を採用した。 ``` mise install bun install bun docs ``` よりも ``` nix run .#docs ``` の方がシンプルな上躓くポイントが少ない。 また、利用できるツールの数も桁違いに多く、バージョンの違いによる エラーなどもほぼない。 Mkdocs を採用した理由はなんとなく。使ったことがない、 というのもある。ぶっちゃけよほど酷くなければなんでもよかった。

Changes

11 changed files (+314/-17)

• .editorconfig
  • @@ -27,3 +27,9 @@ # terraform fmt は 2 スペース以外の指定ができない。
    [*.tf] indent_style = space indent_size = 2 + + # Nix は複数行文字列のインデントに Tab を使うと解釈がおかしくなる + # バグがずっと存在しており治る見込みがない。 + [*.nix] + indent_style = space + indent_size = 2
• .gitignore
  • @@ -35,3 +35,8 @@ .env
    # What: wireit のキャッシュディレクトリ。 .wireit + + # What: Nix の作成するビルド成果物 (へのシンボリックリンク)。 + # 雑すぎる名前な上カレントディレクトリに吐かれ、変更するためには + # 都度 CLI オプションを指定する必要がある。 + result
• docs/.gitignore (new)
  • @@ -0,0 +1,16 @@
    + # SPDX-License-Identifier: AGPL-3.0-only + # Copyright 2025 Shota FUJI + # + # This program is free software: you can redistribute it and/or modify it under the terms + # of the GNU Affero General Public License as published by the Free Software Foundation, + # either version 3 of the License, or (at your option) any later version. + # + # This program is distributed in the hope that it will be useful, but WITHOUT ANY + # WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A + # PARTICULAR PURPOSE. See the GNU Affero General Public License for more details. + # + # You should have received a copy of the GNU Affero General Public License along + # with this program. If not, see <http://www.gnu.org/licenses/>. + + # What: mkdocs のビルド生成物。 + site/
• docs/mkdocs.yml (new)
  • @@ -0,0 +1,34 @@
    + # SPDX-License-Identifier: AGPL-3.0-only + # Copyright 2025 Shota FUJI + # + # This program is free software: you can redistribute it and/or modify it under the terms + # of the GNU Affero General Public License as published by the Free Software Foundation, + # either version 3 of the License, or (at your option) any later version. + # + # This program is distributed in the hope that it will be useful, but WITHOUT ANY + # WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A + # PARTICULAR PURPOSE. See the GNU Affero General Public License for more details. + # + # You should have received a copy of the GNU Affero General Public License along + # with this program. If not, see <http://www.gnu.org/licenses/>. + + site_name: "Yamori ユーザガイド" + docs_dir: "src" + + theme: + name: material + palette: + - media: "(prefers-color-scheme)" + toggle: + icon: material/brightness-auto + name: Switch to light mode + - media: "(prefers-color-scheme: light)" + scheme: default + toggle: + icon: material/brightness-7 + name: Switch to dark mode + - media: "(prefers-color-scheme: dark)" + scheme: slate + toggle: + icon: material/brightness-4 + name: Switch to system preference
• docs/package.nix (new)
  • @@ -0,0 +1,41 @@
    + # SPDX-License-Identifier: AGPL-3.0-only + # Copyright 2025 Shota FUJI + # + # This program is free software: you can redistribute it and/or modify it under the terms + # of the GNU Affero General Public License as published by the Free Software Foundation, + # either version 3 of the License, or (at your option) any later version. + # + # This program is distributed in the hope that it will be useful, but WITHOUT ANY + # WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A + # PARTICULAR PURPOSE. See the GNU Affero General Public License for more details. + # + # You should have received a copy of the GNU Affero General Public License along + # with this program. If not, see <http://www.gnu.org/licenses/>. + + { + stdenvNoCC, + lib, + python313Packages, + }: + stdenvNoCC.mkDerivation { + name = "yamori-docs"; + + nativeBuildInputs = [ + # Project documentation with Markdown / static website generator + # https://www.mkdocs.org/ + python313Packages.mkdocs + + # Material for mkdocs + # https://squidfunk.github.io/mkdocs-material/ + python313Packages.mkdocs-material + ]; + + src = lib.sourceByRegex ./. [ + "^src.*" + "mkdocs.yml" + ]; + + buildPhase = '' + mkdocs build --strict -d $out + ''; + }
• docs/src/directory_structure.md (new)
  • @@ -0,0 +1,20 @@
    + # サポートされるフォルダ構成 + + <!-- + SPDX-License-Identifier: AGPL-3.0-only + Copyright 2025 Shota FUJI + + This program is free software: you can redistribute it and/or modify it under the terms + of the GNU Affero General Public License as published by the Free Software Foundation, + either version 3 of the License, or (at your option) any later version. + + This program is distributed in the hope that it will be useful, but WITHOUT ANY + WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A + PARTICULAR PURPOSE. See the GNU Affero General Public License for more details. + + You should have received a copy of the GNU Affero General Public License along + with this program. If not, see <http://www.gnu.org/licenses/>. + --> + + 集計を開始すると取り込む対象のフォルダ配下のファイルは全て読み込まれます。 + 原則として全ての情報がデータの各行に記載されている必要がありますが、一定のルールに則ったファイル名やフォルダ名、シート名を付けることで冗長な列を省くことができます。
• docs/src/index.md (new)
  • @@ -0,0 +1,19 @@
    + # はじめに + + <!-- + SPDX-License-Identifier: AGPL-3.0-only + Copyright 2025 Shota FUJI + + This program is free software: you can redistribute it and/or modify it under the terms + of the GNU Affero General Public License as published by the Free Software Foundation, + either version 3 of the License, or (at your option) any later version. + + This program is distributed in the hope that it will be useful, but WITHOUT ANY + WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A + PARTICULAR PURPOSE. See the GNU Affero General Public License for more details. + + You should have received a copy of the GNU Affero General Public License along + with this program. If not, see <http://www.gnu.org/licenses/>. + --> + + このドキュメントは年次有給休暇計算ソフトウェア "Yamori" の取り扱い説明書です。
• dprint.jsonc
  • @@ -4,9 +4,26 @@ //
    // SPDX-FileCopyrightText: 2024 Shota FUJI <pockawoooh@gmail.com> // SPDX-License-Identifier: AGPL-3.0-only { - "biome": { - "lineWidth": 90 - }, + "plugins": [ + "https://plugins.dprint.dev/markdown-0.17.8.wasm", + // "Biome is a fast formatter for JavaScript, TypeScript, JSX, TSX, JSON, CSS and GraphQL..." + "https://plugins.dprint.dev/biome-0.7.1.wasm", + "https://plugins.dprint.dev/exec-0.5.0.json@8d9972eee71fa1590e04873540421f3eda7674d0f1aae3d7c788615e7b7413d0", + "https://plugins.dprint.dev/g-plane/pretty_yaml-v0.5.0.wasm", + // "HTML, Vue, Svelte, Astro, Angular, Jinja, Twig, Nunjucks, and Vento files via markup_fmt." + "https://plugins.dprint.dev/g-plane/markup_fmt-v0.18.0.wasm", + "https://plugins.dprint.dev/toml-0.6.3.wasm", + // "Configurable, smart and fast CSS, SCSS, Sass and Less formatter..." + // Biome の CSS は `:state()` がパースエラーになり使い物にならないため、品質の高いこちらを利用している。 + "https://plugins.dprint.dev/g-plane/malva-v0.11.0.wasm" + ], + + // 共通設定 + "lineWidth": 90, + "indentWidth": 2, + + // プラグインごとの設定 + "biome": {}, "markdown": { "lineWidth": 100 },
  • @@ -15,6 +32,10 @@ "commands": [
    { "exts": ["tf"], "command": "terraform fmt -" + }, + { + "exts": ["nix"], + "command": "nixfmt --strict --width={{line_width}} --indent={{indent_width}}" } ] },
  • @@ -28,18 +49,5 @@ "styleIndent": true
    }, "malva": { "useTabs": true - }, - "plugins": [ - "https://plugins.dprint.dev/markdown-0.17.8.wasm", - // "Biome is a fast formatter for JavaScript, TypeScript, JSX, TSX, JSON, CSS and GraphQL..." - "https://plugins.dprint.dev/biome-0.7.1.wasm", - "https://plugins.dprint.dev/exec-0.5.0.json@8d9972eee71fa1590e04873540421f3eda7674d0f1aae3d7c788615e7b7413d0", - "https://plugins.dprint.dev/g-plane/pretty_yaml-v0.5.0.wasm", - // "HTML, Vue, Svelte, Astro, Angular, Jinja, Twig, Nunjucks, and Vento files via markup_fmt." - "https://plugins.dprint.dev/g-plane/markup_fmt-v0.18.0.wasm", - "https://plugins.dprint.dev/toml-0.6.3.wasm", - // "Configurable, smart and fast CSS, SCSS, Sass and Less formatter..." - // Biome の CSS は `:state()` がパースエラーになり使い物にならないため、品質の高いこちらを利用している。 - "https://plugins.dprint.dev/g-plane/malva-v0.11.0.wasm" - ] + } }
• flake.lock (new)
  • @@ -0,0 +1,61 @@
    + { + "nodes": { + "flake-utils": { + "inputs": { + "systems": "systems" + }, + "locked": { + "lastModified": 1731533236, + "narHash": "sha256-l0KFg5HjrsfsO/JpG+r7fRrqm12kzFHyUHqHCVpMMbI=", + "owner": "numtide", + "repo": "flake-utils", + "rev": "11707dc2f618dd54ca8739b309ec4fc024de578b", + "type": "github" + }, + "original": { + "owner": "numtide", + "repo": "flake-utils", + "type": "github" + } + }, + "nixpkgs": { + "locked": { + "lastModified": 1753399495, + "narHash": "sha256-7XG/QBqhrYOyA2houjRTL2NMa7IKZZ/somBqr+Q/6Wo=", + "owner": "nixos", + "repo": "nixpkgs", + "rev": "0d00f23f023b7215b3f1035adb5247c8ec180dbc", + "type": "github" + }, + "original": { + "owner": "nixos", + "ref": "nixpkgs-unstable", + "repo": "nixpkgs", + "type": "github" + } + }, + "root": { + "inputs": { + "flake-utils": "flake-utils", + "nixpkgs": "nixpkgs" + } + }, + "systems": { + "locked": { + "lastModified": 1681028828, + "narHash": "sha256-Vy1rq5AaRuLzOxct8nz4T6wlgyUR7zLU309k9mBC768=", + "owner": "nix-systems", + "repo": "default", + "rev": "da67096a3b9bf56a91d16901293e51ba5b49a27e", + "type": "github" + }, + "original": { + "owner": "nix-systems", + "repo": "default", + "type": "github" + } + } + }, + "root": "root", + "version": 7 + }
• flake.lock.license (new)
  • @@ -0,0 +1,2 @@
    + SPDX-License-Identifier: AGPL-3.0-only + SPDX-FileCopyrightText: 2025 Shota FUJI
• flake.nix (new)
  • @@ -0,0 +1,85 @@
    + # SPDX-License-Identifier: AGPL-3.0-only + # Copyright 2025 Shota FUJI + # + # This program is free software: you can redistribute it and/or modify it under the terms + # of the GNU Affero General Public License as published by the Free Software Foundation, + # either version 3 of the License, or (at your option) any later version. + # + # This program is distributed in the hope that it will be useful, but WITHOUT ANY + # WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A + # PARTICULAR PURPOSE. See the GNU Affero General Public License for more details. + # + # You should have received a copy of the GNU Affero General Public License along + # with this program. If not, see <http://www.gnu.org/licenses/>. + + { + inputs = { + nixpkgs.url = "github:nixos/nixpkgs/nixpkgs-unstable"; + flake-utils.url = "github:numtide/flake-utils"; + }; + + outputs = + { + self, + nixpkgs, + flake-utils, + }: + flake-utils.lib.eachDefaultSystem ( + system: + let + pkgs = nixpkgs.legacyPackages.${system}; + in + { + packages = { + docs = pkgs.callPackage ./docs/package.nix { }; + }; + + apps = { + # nix run .#docs + # -------------- + # ドキュメントの開発サーバを起動する。オプションは "--" の後に指定する。 + # 例: nix run .#docs -- --help + docs = + let + server = pkgs.symlinkJoin { + name = "server-docs"; + + nativeBuildInputs = [ pkgs.makeWrapper ]; + + paths = [ + (pkgs.python3.withPackages ( + python: with python; [ + python.mkdocs + python.mkdocs-material + ] + )) + ]; + + postBuild = '' + wrapProgram $out/bin/mkdocs \ + --add-flags 'serve' \ + --add-flags '--config-file' \ + --add-flags 'docs/mkdocs.yml' + ''; + }; + in + { + type = "app"; + program = "${server}/bin/mkdocs"; + }; + }; + + devShell = pkgs.mkShell { + packages = with pkgs; [ + # Official formatter for Nix code + # https://hackage.haskell.org/package/nixfmt + nixfmt-rfc-style + + # Copyright and license linter based on SPDX + # https://github.com/fsfe/reuse-tool + reuse + ]; + }; + } + ); + }