mosecorg · kemingy · Feb 27, 2023 · Feb 25, 2023 · Feb 25, 2023 · Feb 25, 2023
diff --git a/.github/workflows/page.yml b/.github/workflows/page.yml
@@ -46,14 +46,12 @@ jobs:
         pip install -e .[dev,doc,plugin]
     - name: Generate docs
       run: |
-        mkdocs build
-        cd site
-        touch .nojekyll
+        cd docs && make html
     - name: Upload artifact
       uses: actions/upload-pages-artifact@v1
       with:
         # Upload entire repository
-        path: 'site'
+        path: 'docs/build/html'
     - name: Deploy to GitHub Pages
       id: deployment
       uses: actions/deploy-pages@v1
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -1,13 +1,15 @@
+# Contributing to `Mosec`
+
 Before contributing to this repository, please first discuss the change you wish to make via issue, email, or any other method with the owners of this repository before making a change.
 
-### Pull Request Process
+## Pull Request Process
 
 1. After you have forked this repository, you could use `make install` for *the first time* to install the local development dependencies; afterward, you may use `make dev` to build the library when you have made any code changes.
 2. Before committing your changes, you can use `make format && make lint` to ensure the codes follow our style standards.
 3. Please add corresponding tests to your change if that's related to new feature or API, and ensure `make test` can pass.
 4. Submit your pull request.
 
-### Contacts
+## Contacts
 
 - Keming <kemingy94@gmail.com>
 - zclzc <lkevinzc@gmail.com>
diff --git a/Makefile b/Makefile
@@ -1,6 +1,6 @@
 .DEFAULT_GOAL:=dev
 
-PY_SOURCE_FILES=mosec tests examples scripts setup.py
+PY_SOURCE_FILES=mosec tests examples setup.py
 RUST_SOURCE_FILES=src/*
 
 install:
@@ -33,7 +33,8 @@ test_all: dev
 	RUST_BACKTRACE=1 cargo test -vv
 
 doc:
-	mkdocs serve
+	@cd docs && make html && cd ../
+	@python -m http.server -d docs/build/html
 
 clean:
 	@cargo clean

diff --git a/docs/Makefile b/docs/Makefile
@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = source
+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)
diff --git a/docs/argument.md b/docs/argument.md
diff --git a/docs/contributing.md b/docs/contributing.md
diff --git a/docs/example/stable_diffusion.md b/docs/example/stable_diffusion.md
diff --git a/docs/index.md b/docs/index.md
diff --git a/docs/interface.md b/docs/interface.md
diff --git a/docs/make.bat b/docs/make.bat
@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=source
+set BUILDDIR=build
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.https://www.sphinx-doc.org/
+	exit /b 1
+)
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd
diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -0,0 +1,65 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# For the full list of built-in configuration values, see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+import os
+import sys
+
+sys.path.insert(0, os.path.abspath("../.."))
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+
+project = "mosec"
+copyright = "2023, mosec maintainers"
+author = "mosec maintainers"
+release = "latest"
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = [
+    "sphinx.ext.viewcode",
+    "sphinx.ext.autodoc",
+    "sphinx.ext.githubpages",
+    "sphinx.ext.napoleon",
+    "myst_parser",
+    "sphinx_copybutton",
+    "sphinxcontrib.programoutput",
+    "sphinx_autodoc_typehints",
+    "sphinxext.opengraph",
+]
+
+templates_path = ["_templates"]
+exclude_patterns = []
+source_suffix = [".rst", ".md"]
+master_doc = "index"
+language = "en"
+
+# Extension configuration
+myst_heading_anchors = 3
+autodoc_member_order = "bysource"
+# https://www.sphinx-doc.org/en/master/usage/extensions/napoleon.html
+napoleon_attr_annotations = True
+napoleon_include_init_with_doc = True
+napoleon_use_admonition_for_references = True
+# https://sphinxext-opengraph.readthedocs.io/en/latest/
+ogp_site_url = "https://mosecorg.github.io/mosec/"
+ogp_image = "https://user-images.githubusercontent.com/38581401/134487662-49733d45-2ba0-4c19-aa07-1f43fd35c453.png"
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+html_theme = "furo"
+html_logo = "https://user-images.githubusercontent.com/38581401/134487662-49733d45-2ba0-4c19-aa07-1f43fd35c453.png"
+html_static_path = ["_static"]
+
+# Theme
+html_theme_options = {
+    "sidebar_hide_name": True,
+    "navigation_with_keys": True,
+    "source_repository": "https://github.com/mosecorg/mosec/",
+    "source_branch": "main",
+    "source_directory": "docs/",
+}
diff --git a/docs/source/development/contributing.md b/docs/source/development/contributing.md
@@ -0,0 +1,2 @@
+```{include} ../../../CONTRIBUTING.md
+```
diff --git a/docs/design/index.md → docs/source/development/design.md b/docs/design/index.md → docs/source/development/design.md
@@ -1 +1,3 @@
+# Design
+
 We will explain the detail of our designs in this section.
diff --git a/docs/source/development/index.md b/docs/source/development/index.md
@@ -0,0 +1,13 @@
+# Development
+
+```{toctree}
+---
+hidden:
+---
+
+design
+contributing
+```
+
+- {doc}`design`
+- {doc}`contributing`
diff --git a/docs/example/echo.md → docs/source/examples/echo.md b/docs/example/echo.md → docs/source/examples/echo.md
@@ -1,19 +1,25 @@
+# Echo Example
+
 An echo server is usually the very first server you wanna implement to get familiar with the framework.
 
 This server sleeps for a given period and return. It is a simple illustration of how **multi-stage workload** is implemented. It also shows how to write a simple **validation** for input data.
 
 The default JSON protocol will be used since the (de)serialization methods are not overridden in this demo. In particular, the input `data` of `Preprocess`'s `forward` is a dictionary decoded by JSON from the request body's bytes; and the output dictionary of `Postprocess`'s `forward` will be JSON-encoded as a mirrored process.
 
-#### **`echo.py`**
+## **`echo.py`**
 
-```python
---8<-- "examples/echo.py"
+```{include} ../../../examples/echo.py
+:code: python
 ```
 
-#### Start
+## Start
 
-    python echo.py
+```shell
+python echo.py
+```
 
-#### Test
+## Test
 
-    http :8000/inference time=1.5
+```shell
+http :8000/inference time=1.5
+```
diff --git a/docs/example/env.md → docs/source/examples/env.md b/docs/example/env.md → docs/source/examples/env.md
@@ -1,19 +1,25 @@
+# Customized GPU Allocation
+
 This is an example demonstrating how to give different worker processes customized environment variables to control things like GPU device allocation, etc.
 
 Assume your machine has 4 GPUs, and you hope to deploy your model to all of them to handle inference requests in parallel, maximizing your service's throughput. With MOSEC, we provide parallel workers with customized environment variables to satisfy the needs.
 
 As shown in the codes below, we can define our inference worker together with a list of environment variable dictionaries, each of which will be passed to the corresponding worker process. For example, if we set `CUDA_VISIBLE_DEVICES` to `0-3`, (the same copy of) our model will be deployed on 4 different GPUs and be queried in parallel, largely improving the system's throughput. You could verify this either from the server logs or the client response.
 
-#### **`custom_env.py`**
+## **`custom_env.py`**
 
-```python
---8<-- "examples/custom_env.py"
+```{include} ../../../examples/custom_env.py
+:code: python
 ```
 
-#### Start
+## Start
 
-    python custom_env.py
+```shell
+python custom_env.py
+```
 
-#### Test
+## Test
 
-    curl -X POST http://127.0.0.1:8000/inference -d '{"dummy": 0}'
+```shell
+http :8000/inference dummy=0
+```
diff --git a/docs/example/index.md → docs/source/examples/index.md b/docs/example/index.md → docs/source/examples/index.md
@@ -1,11 +1,31 @@
+# Examples
+
+```{toctree}
+---
+hidden:
+---
+
+echo
+env
+ipc
+jax
+metric
+pytorch
+stable_diffusion
+```
+
 We provide examples across different ML frameworks and for various tasks in this section.
 
-## Get started
+## Requirements
 
 All the examples in this section are self-contained and tested. Feel free to grab one and run:
 
-    python model_server.py
+```shell
+python model_server.py
+```
 
 To test the server, we use [`httpie`](https://github.com/httpie/httpie) and [`httpx`](https://github.com/encode/httpx) by default. You can have other choices but if you want to install them:
 
-    pip install httpie httpx
+```shell
+pip install httpie httpx
+```
diff --git a/docs/example/ipc.md → docs/source/examples/ipc.md b/docs/example/ipc.md → docs/source/examples/ipc.md
@@ -1,3 +1,5 @@
+# Shared Memory IPC
+
 This is an example demonstrating how you can enable the plasma shared memory store or customize your own IPC wrapper.
 
 Mosec's multi-stage pipeline requires the output data from the previous stage to be transferred to the next stage across python processes. This is coordinated via Unix domain socket between every Python worker process from all stages and the Rust controller process.
@@ -6,16 +8,20 @@ By default, we serialize the data and directly transfer the bytes over the socke
 
 The additional subprocess can be registered as a daemon thus it will be checked by mosec regularly and trigger graceful shutdown when the daemon exits.
 
-#### **`plasma_shm_ipc.py`**
+## **`plasma_shm_ipc.py`**
 
-```python
---8<-- "examples/plasma_shm_ipc.py"
+```{include} ../../../examples/plasma_shm_ipc.py
+:code: python
 ```
 
-#### Start
+## Start
 
-    python plasma_shm_ipc.py
+```shell
+python plasma_shm_ipc.py
+```
 
-#### Test
+## Test
 
-    curl -X POST http://127.0.0.1:8000/inference -d '{"size": 100}'
+```shell
+http :8000/inference size=100
+```