Add JupyterBook (#160)

# 変更点
-
従来のGitHubPagesのルートページ（doc/index.html）の代わりにJupyterBook製のHTMLが利用されるように変更を加えました
- 既存のAPIリファレンスは同じURLかつ同じドキュメント生成方法のままにしました。
   - これに関連して、JupyterBook製のHTMLから既存のAPIリファレンスへのリンクは外部リンクの形としています。 

# 相談事項
-
TaskおよびGitHubActionsの運用について、なるべくTask側に各種コマンドを集約し、GitHubActionsはそれを実行するだけにする方が良いと考えていますが、この認識は間違いないでしょうか？
-
この認識が正しい場合、GitHubActionsのドキュメント生成のワークフローがTaskを使っていない形をしているので、修正が必要と考えています。
-
既存のAPIリファレンスのうち、Python製のものはSphinxのAutoAPIをJupyterBook内で使うことで統合が可能になります。その対応を本PRに含めた方が良いでしょうか？
   - 統合する場合のデメリットとして、APIリファレンス毎に表示するAPIをコントロールできなくなるという問題があります。
-
[従来のOMMXのAPIリファレンスはAutoAPIのオプションを設定すること](https://github.com/Jij-Inc/ommx/blob/94b9016bf2a0ca250c1dbd7ae40798d6341e28bf/python/ommx/docs/source/conf.py#L56-L60)でprotobuf特有の不要なAPIをなるべく表示しないようにしています。こういった設定が個別にできなくなります。
     
 # 補足事項

https://github.com/Jij-Inc/ommx/actions/runs/12040838304/job/33571508249?pr=160#step:6:28

上記のGitHubActionsのログにあるArtifactをローカルにダウンロードし、`index.html`をブラウザで開くことで見た目を確認することができます。

.github/workflows/doc.yml

@@ -19,6 +19,32 @@ concurrency:
   cancel-in-progress: true
 
 jobs:
+  jupyter-book:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.9"
+
+      - name: Install dependencies
+        run: |
+          pip install -r requirements.txt
+          pip install -r doc/requirements.txt
+
+      - name: Build Jupyter Book
+        run: jupyter-book build doc
+
+      - name: Upload HTML
+        uses: actions/upload-artifact@v4
+        with:
+          name: doc-jupyter-book
+          path: ./doc/_build/html
+          retention-days: 30
+
   protobuf:
     runs-on: ubuntu-latest
     steps:
@@ -109,9 +135,15 @@ jobs:
           retention-days: 30
 
   package:
-    needs: [protobuf, rust, python]
+    needs: [jupyter-book, protobuf, rust, python]
     runs-on: ubuntu-latest
     steps:
+      - name: Download HTML of JupyterBook
+        uses: actions/download-artifact@v4
+        with:
+          name: doc-jupyter-book
+          path: ./doc
+
       - name: Download HTML of protobuf
         uses: actions/download-artifact@v4
         with:

.gitignore

@@ -26,3 +26,6 @@ python/**/build/
 python/**/dist/
 python/**/*.egg-info/
 python/**/*.so
+
+# Doc
+doc/_build/

Taskfile.yml

@@ -4,6 +4,15 @@ version: "3"
 
 tasks:
   # Documents
+  install_doc:
+    cmds:
+      - pip install -r requirements.txt
+      - pip install -r doc/requirements.txt
+
+  build_book:
+    cmds:
+      - jupyter-book build doc
+
   doc_rust:
     cmds:
       - cargo doc --no-deps -p ommx

doc/_config.yml

@@ -0,0 +1,34 @@
+# Book settings
+# Learn more at https://jupyterbook.org/customize/config.html
+
+title: OMMX
+author: Jij Inc.
+# logo: logo.png  # TODO: ロゴが出来たら設定すること
+
+# Force re-execution of notebooks on each build.
+# See https://jupyterbook.org/content/execute.html
+execute:
+  execute_notebooks: force
+
+# Define the name of the latex output file for PDF builds
+latex:
+  latex_documents:
+    targetname: book.tex
+
+# Information about where the book exists on the web
+repository:
+  url: https://github.com/Jij-Inc/ommx  # Online location of your book
+  path_to_book: docs  # Optional path to your book, relative to the repository root
+  branch: main  # Which branch of the repository should be used when creating links (optional)
+
+# Add GitHub buttons to your book
+# See https://jupyterbook.org/customize/config.html#add-a-link-to-your-repository
+html:
+  # favicon: "./logo.png"  # TODO: ロゴが出来たら設定すること
+  use_issues_button: true
+  use_repository_button: true
+
+launch_buttons:
+  notebook_interface: "classic"
+  binderhub_url: "https://mybinder.org"
+  colab_url: "https://colab.research.google.com"

doc/_toc.yml

@@ -0,0 +1,36 @@
+# Table of contents
+# Learn more at https://jupyterbook.org/customize/toc.html
+
+format: jb-book
+root: introduction
+parts:
+- caption: "Concept"
+  chapters:
+  - file: concept/architecture
+- caption: "Tutorial"
+  chapters:
+  - file: tutorial/solve_with_scip
+  - file: tutorial/share_artifact
+  - file: tutorial/pull_artifact
+- caption: "OMMX Message"
+  chapters:
+  - file: ommx_message/architecture
+- caption: "OMMX Artifact"
+  chapters:
+  - file: ommx_artifact/architecture
+- caption: "OMMX Ecosystem"
+  chapters:
+  - file: ommx_ecosystem/links
+- caption: "API Reference"
+  chapters:
+  - url: https://jij-inc.github.io/ommx/protobuf.html
+    title: "OMMX Message Schema"
+  - url: https://jij-inc.github.io/ommx/rust/ommx/index.html
+    title: "OMMX Rust SDK"
+  - url: https://jij-inc.github.io/ommx/python/ommx/index.html
+    title: "OMMX Python SDK"
+  - url: https://jij-inc.github.io/ommx/python/ommx-python-mip-adapter/index.html
+    title: "OMMX Python-MIP Adapter"
+- caption: "Release Note"
+  chapters:
+  - file: release_note/ommx-x.y.z

doc/concept/architecture.ipynb

@@ -0,0 +1,20 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# 設計思想\n",
+    "\n",
+    "TBW"
+   ]
+  }
+ ],
+ "metadata": {
+  "language_info": {
+   "name": "python"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 2
+}

doc/introduction.ipynb

@@ -0,0 +1,20 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# はじめに\n",
+    "\n",
+    "TBW"
+   ]
+  }
+ ],
+ "metadata": {
+  "language_info": {
+   "name": "python"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 2
+}

doc/ommx_artifact/architecture.ipynb

@@ -0,0 +1,70 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "OMMX Artifact Design\n",
+    "=====================\n",
+    "\n",
+    "OMMX Artifact is a specification for packaging and distributing OMMX Messages and associated metadata over the OCI Artifact defined in [OCI Image specification 1.1.0](https://github.com/opencontainers/image-spec/blob/v1.1.0/spec.md) and [OCI Distribution specification 1.1.0](https://github.com/opencontainers/distribution-spec/blob/v1.1.0/spec.md).\n",
+    "\n",
+    "Metadata and Reference\n",
+    "-----------------------\n",
+    "\n",
+    "The problem that metadata should solve is the reference between data.\n",
+    "\n",
+    "- Even if the schema of the data is defined, the moment it is saved to a file or DB and separated from the application, the relationship between the data is lost.\n",
+    "  - For example, within the solver process, it is clear which Instance the Solution is for, but after saving to a file or DB, it is no longer apparent.\n",
+    "\n",
+    "- Wouldn't it be better to always save the Solution and Instance together in a file?\n",
+    "  - This simply increases the amount of data to be saved. Considering cases where many Solutions are generated by changing parameters for a single Instance, saving all Instances is inefficient. Moreover, as the amount of data increases, the overhead of exchanging that data also becomes significant.\n",
+    "\n",
+    "- Therefore, a reference mechanism is introduced.\n",
+    "  - Reference refers to sufficient information to obtain the data even without the actual data.\n",
+    "  - If the data is not shared between machines, the path in the file system can serve as a reference, but if it is shared over the Internet, a URI is needed. Introducing a reference function is closely tied to how to retain and obtain the data.\n",
+    "\n",
+    "Specification\n",
+    "--------------\n",
+    "\n",
+    "OMMX Artifact is an OCI Artifact of media type `application/org.ommx.v1.artifact`.\n",
+    "OCI Artifact is represented as an [OCI Image manifest](https://github.com/opencontainers/image-spec/blob/v1.1.0/manifest.md).\n",
+    "OMMX Artifact is a collection of `config`, `layers`, and annotations.\n",
+    "\n",
+    "- `config` is a JSON blob with the following media types:\n",
+    "  - `application/org.ommx.v1.config+json`\n",
+    "- `layers` consists of the following blobs:\n",
+    "  - `application/org.ommx.v1.solution` blob with the following annotations:\n",
+    "    - `org.ommx.v1.solution.instance`: (digest) The corresponding instance of the solution\n",
+    "    - `org.ommx.v1.solution.solver`: (JSON) The solver information which generated the solution as a JSON\n",
+    "    - `org.ommx.v1.solution.parameters`: (JSON) Solver parameters used to generate the solution as a JSON\n",
+    "    - `org.ommx.v1.solution.start`: (RFC3339) The start time of the solution as a RFC3339 string\n",
+    "    - `org.ommx.v1.solution.end`: (RFC3339) The end time of the solution as a RFC3339 string\n",
+    "  - `application/org.ommx.v1.instance` blob with the following annotations:\n",
+    "    - `org.ommx.v1.instance.title`: (String) The title of this instance\n",
+    "    - `org.ommx.v1.instance.created`: (RFC3339) When this instance was created\n",
+    "    - `org.ommx.v1.instance.authors`: (String) Name of authors. Multiple authors are separated by comma (`,`)\n",
+    "    - `org.ommx.v1.instance.license`: ([SPDX License Identifier](https://spdx.org/licenses/)) License of this instance\n",
+    "    - `org.ommx.v1.instance.dataset`: (String) Name of the dataset this instance belongs to\n",
+    "    - `org.ommx.v1.instance.variables`: (Integer) Number of variables in this instance\n",
+    "    - `org.ommx.v1.instance.constraints`: (Integer) Number of constraints in this instance\n",
+    "  - `application/vnd.numpy`: NumPy's ndarray with NPY format\n",
+    "  - `application/vnd.apache.parquet`: DataFrame with Parquet format\n",
+    "  - And other blobs with appropriate media types. The media type SHOULD be registered in the [IANA media type registry](https://www.iana.org/assignments/media-types/media-types.xhtml).\n",
+    "    - Users can add arbitrary annotation to arbitrary layer. `org.ommx.user.` prefix is reserved for user-defined annotations.\n",
+    "- Annotations in manifest:\n",
+    "  - TBA\n",
+    "\n",
+    "Note that other annotations listed above are also allowed.\n",
+    "The key may not start with `org.ommx.v1.`, but must be a valid reverse domain name as specified by OCI specification."
+   ]
+  }
+ ],
+ "metadata": {
+  "language_info": {
+   "name": "python"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 2
+}

doc/ommx_ecosystem/links.ipynb

@@ -0,0 +1,20 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# 周辺ツールへのリンク集\n",
+    "\n",
+    "TBW"
+   ]
+  }
+ ],
+ "metadata": {
+  "language_info": {
+   "name": "python"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 2
+}

doc/ommx_message/architecture.ipynb

@@ -0,0 +1,53 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "OMMX Message Design\n",
+    "=============\n",
+    "\n",
+    "[![doc](https://img.shields.io/badge/Protocol-Documentation-blue)](https://jij-inc.github.io/ommx/protobuf.html)\n",
+    "\n",
+    "## Why OMMX Message based on Protocol Buffers? Why not [JSON](https://www.json.org/json-en.html), [CBOR](https://cbor.io/), or [HDF5](https://www.hdfgroup.org/solutions/hdf5/)?\n",
+    "\n",
+    ":zap: We need to define a data schema for messages exchanged between applications, services, and databases that make up OROps.\n",
+    "\n",
+    "We have to discuss the following points to answer the question.\n",
+    "\n",
+    "- Where OMMX is used?\n",
+    "- Why schema is required?\n",
+    "- Text-based or Binary-based?\n",
+    "- Why Protocol Buffers?\n",
+    "\n",
+    "Note that this is a **better** selection, not the **best** selection. We have to keep considering these points and change the selection if necessary.\n",
+    "\n",
+    "### Where OMMX is used?\n",
+    "\n",
+    "Mathematical programming has been a subject of study in academic fields for a considerable period of time, and numerous software tools have been developed to improve the solving capability. However, these tools are basically designed for use in a research process. When we attempt to use these invaluable tools in a real-world business process, we refer to it as \"OROps\" (OR = operations research), like \"MLOps\" in machine-learning field, we have to face many problems. The most significant problem is the lack of interoperability between tools. We have to convert data between tools, and it is a time-consuming and error-prone process. OMMX is designed to solve this problem.\n",
+    "\n",
+    "### Why schema is required?\n",
+    "Different from research process where few researchers use and create few tools, in OROps, many developers use and create many tools. The interoperability between tools becomes significant issue due to this point. It is possible for human to manage input and output data stored in general purpose data format like JSON or HDF5 for few tools, but it is hard for many tools. Thus, we have to introduce machine-readable schema.\n",
+    "\n",
+    "### Text-based or Binary-based?\n",
+    "TBW\n",
+    "\n",
+    "### Why Protocol Buffers?\n",
+    "TBW\n",
+    "\n",
+    "## Compatibility\n",
+    "\n",
+    "- OMMX defines a protocol buffers schema with version like `v1`, `v2`, etc. `v1` schema has a namesapce `ommx.v1`.\n",
+    "- Schemas in `ommx.v1` will be compatible after [ommx.v1 schema release](https://github.com/Jij-Inc/ommx/milestone/3). Note that the schema can be changed incompatible way until this release.\n",
+    "- `v2` schema with namespace `ommx.v2` will start developing if we need to change the schema in incompatible way after `ommx.v1` release. Compatible changes will be made in `v1` schema also after its release. We never create namespaces like `ommx.v1_1`."
+   ]
+  }
+ ],
+ "metadata": {
+  "language_info": {
+   "name": "python"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 2
+}

doc/release_note/ommx-x.y.z.ipynb

@@ -0,0 +1,20 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# OMMX x.y.z Release Note\n",
+    "\n",
+    "TBW"
+   ]
+  }
+ ],
+ "metadata": {
+  "language_info": {
+   "name": "python"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 2
+}

doc/requirements.txt

@@ -0,0 +1,3 @@
+# This file is used to generate the documentation.
+nbconvert >= 7.16.4
+jupyter-book >= 1.0.0, < 2.0.0

doc/tutorial/pull_artifact.ipynb

@@ -0,0 +1,20 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# データを取得する\n",
+    "\n",
+    "TBW"
+   ]
+  }
+ ],
+ "metadata": {
+  "language_info": {
+   "name": "python"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 2
+}