Merge pull request #5635 from FederatedAI/doc-2.0.0-test

fix doc build

.readthedocs.yml

@@ -0,0 +1,15 @@
+version: 2
+
+mkdocs:
+  # configuration: .readthedocs.mkdocs.yml
+  fail_on_warning: false
+
+formats: all
+
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.8"
+python:
+  install:
+  - requirements: doc/mkdocs/requirements.txt

doc/index.md

@@ -0,0 +1,4 @@
+---
+template: overrides/home.html
+title: Home
+---

doc/mkdocs/README.md

@@ -0,0 +1,106 @@
+# Build
+
+# prepare
+
+We use setup.py to hook docs generation in readthedocs, just run 
+
+```bash
+python doc/mkdocs/setup.py 
+```
+
+## use docker
+
+At repo root, execute
+
+```sh
+docker run --rm -it -p 8000:8000 -v ${PWD}:/docs sagewei0/mkdocs  
+```
+
+to serve docs in http://localhost:8000
+
+or
+
+```sh
+docker run --rm -it -p 8000:8000 -v ${PWD}:/docs sagewei0/mkdocs build
+```
+
+to build docs to `site` folder.
+
+## manually
+
+[`mkdocs-material`](https://pypi.org/project/mkdocs-material/) and servel plugins are needed to build this docs
+
+Fisrt, create an python virtual environment
+
+```sh
+python3 -m venv "fatedocs"
+source fatedocs/bin/activate
+pip install -U pip
+```
+And then install requirements
+
+```sh
+pip install -r doc/mkdocs/requirements.txt
+```
+
+Now, use
+
+```sh
+mkdocs serve
+```
+
+at repo root to serve docs or
+
+use 
+
+```sh
+mkdocs build
+```
+
+at repo root to build docs to folder `site`
+
+
+# Develop guide
+
+We use [mkdocs-material](https://squidfunk.github.io/mkdocs-material/) to build our docs. 
+Servel markdown extensions are really useful to write pretty documents such as 
+[admonitions](https://squidfunk.github.io/mkdocs-material/reference/admonitions/) and 
+[content-tabs](https://squidfunk.github.io/mkdocs-material/reference/content-tabs/).
+
+Servel plugins are introdused to makes mkdocs-material much powerful:
+
+
+- [mkdocstrings](https://mkdocstrings.github.io/usage/) 
+    automatic documentation from sources code. We mostly use this to automatic generate
+    `params api` for `federatedml`.
+
+- [awesome-pages](https://github.com/lukasgeiter/mkdocs-awesome-pages-plugin)
+    for powerful nav rule
+
+- [i18n](https://ultrabug.github.io/mkdocs-static-i18n/)
+    for multi-languege support
+
+- [mkdocs-jupyter](https://github.com/danielfrg/mkdocs-jupyter)
+    for jupyter format support
+
+- [mkdocs-simple-hooks](https://github.com/aklajnert/mkdocs-simple-hooks)
+    for simple plugin-in
+
+## macro extension
+
+### include examples
+
+```
+<!-- {% include-examples "<name>" %} -->
+```
+extract all components's examples(pipeline, dsl v1, dsl v2) from `examples` folder
+
+### include example
+
+```
+<!-- {% include-example "???" %} -->
+```
+
+extract source code `???` from repo.
+
+

doc/mkdocs/css/custom.css

@@ -0,0 +1,39 @@
+/* Indentation. */
+div.doc-contents:not(.first) {
+    padding-left: 25px;
+    border-left: 4px solid rgba(230, 230, 230);
+    margin-bottom: 80px;
+}
+
+/* Don't capitalize names. */
+h5.doc-heading {
+    text-transform: none !important;
+}
+
+/* Don't use vertical space on hidden ToC entries. */
+h6.hidden-toc {
+    margin: 0 !important;
+    position: relative;
+    top: -70px;
+}
+
+h6.hidden-toc::before {
+    margin-top: 0 !important;
+    padding-top: 0 !important;
+}
+
+/* Don't show permalink of hidden ToC entries. */
+h6.hidden-toc a.headerlink {
+    display: none;
+}
+
+/* Avoid breaking parameters name, etc. in table cells. */
+td code {
+    word-break: normal !important;
+}
+
+/* For pieces of Markdown rendered in table cells. */
+td p {
+    margin-top: 0 !important;
+    margin-bottom: 0 !important;
+}

doc/mkdocs/css/extra.css

@@ -0,0 +1,34 @@
+/* Remove default title on the page */
+.md-content__inner h1:first-child {
+  display: none;
+}
+
+/* Adjust to 2px to align with the title */
+.md-logo {
+  padding-top: 6px;
+}
+
+.btn {
+  border: none;
+  padding: 14px 28px;
+  cursor: pointer;
+  display: inline-block;
+
+  background: #009688;
+  color: white;
+}
+
+.btn:hover {
+  background: #00bfa5;
+  color: white;
+}
+
+.center {
+  display: block;
+  margin-left: auto;
+  margin-right: auto;
+}
+
+.text-center {
+  text-align: center;
+}

doc/mkdocs/css/termynal.css

@@ -0,0 +1,110 @@
+/**
+ * termynal.js
+ *
+ * @author Ines Montani <[email protected]>
+ * @version 0.0.1
+ * @license MIT
+ */
+
+:root {
+    --color-bg: #eee8d5;
+    --color-text: #073642;
+    --color-text-subtle: #cb4b16;
+    background: linear-gradient(to right, #3a1c71, #d76d77, #ffaf7b);
+}
+
+[data-termynal] {
+    width: 750px;
+    max-width: 100%;
+    background: var(--color-bg);
+    color: var(--color-text);
+    font-size: 18px;
+    /* font-family: 'Fira Mono', Consolas, Menlo, Monaco, 'Courier New', Courier, monospace; */
+    font-family: 'Roboto Mono', 'Fira Mono', Consolas, Menlo, Monaco, 'Courier New', Courier, monospace;
+    border-radius: 4px;
+    padding: 75px 45px 35px;
+    position: relative;
+    -webkit-box-sizing: border-box;
+            box-sizing: border-box;
+}
+
+[data-termynal]:before {
+    content: '';
+    position: absolute;
+    top: 15px;
+    left: 15px;
+    display: inline-block;
+    width: 15px;
+    height: 15px;
+    border-radius: 50%;
+    /* A little hack to display the window buttons in one pseudo element. */
+    background: #d9515d;
+    -webkit-box-shadow: 25px 0 0 #f4c025, 50px 0 0 #3ec930;
+            box-shadow: 25px 0 0 #f4c025, 50px 0 0 #3ec930;
+}
+
+[data-termynal]:after {
+    content: 'bash';
+    position: absolute;
+    color: var(--color-text-subtle);
+    top: 5px;
+    left: 0;
+    width: 100%;
+    text-align: center;
+}
+
+a[data-terminal-control] {
+    text-align: right;
+    display: block;
+    color: #aebbff;
+}
+
+[data-ty] {
+    display: block;
+    line-height: 2;
+}
+
+[data-ty]:before {
+    /* Set up defaults and ensure empty lines are displayed. */
+    content: '';
+    display: inline-block;
+    vertical-align: middle;
+}
+
+[data-ty="input"]:before,
+[data-ty-prompt]:before {
+    margin-right: 0.75em;
+    color: var(--color-text-subtle);
+}
+
+[data-ty="input"]:before {
+    content: '$';
+}
+
+[data-ty][data-ty-prompt]:before {
+    content: attr(data-ty-prompt);
+}
+
+[data-ty-cursor]:after {
+    content: attr(data-ty-cursor);
+    font-family: monospace;
+    margin-left: 0.5em;
+    -webkit-animation: blink 1s infinite;
+            animation: blink 1s infinite;
+}
+
+
+/* Cursor animation */
+
+@-webkit-keyframes blink {
+    50% {
+        opacity: 0;
+    }
+}
+
+@keyframes blink {
+    50% {
+        opacity: 0;
+    }
+}
+

doc/mkdocs/docker/Dockerfile

@@ -0,0 +1,31 @@
+FROM python:3.9.2-alpine3.13
+
+# Environment variables
+ENV PACKAGES=/usr/local/lib/python3.9/site-packages
+ENV PYTHONDONTWRITEBYTECODE=1
+
+# Set build directory
+WORKDIR /tmp
+
+COPY requirements.txt .
+
+RUN set -e ;\
+    apk upgrade --update-cache -a ;\
+    apk add --no-cache libstdc++ libffi-dev ;\
+    apk add --no-cache --virtual .build gcc g++ musl-dev python3-dev cargo openssl-dev git;\
+    pip install --no-cache-dir -r requirements.txt
+
+# clean 
+RUN apk del .build ;\
+    rm -rf /tmp/* /root/.cache
+
+# Set working directory
+WORKDIR /docs
+
+# Expose MkDocs development server port
+EXPOSE 8000
+
+ENV PYTHONPATH=$PYTHONPATH:/docs/python
+# Start development server by default
+ENTRYPOINT ["mkdocs"]
+CMD ["serve", "--dev-addr=0.0.0.0:8000"]

doc/mkdocs/docker/README.md

@@ -0,0 +1,25 @@
+# Image for build FATE's documents
+
+This image is modified from [mkdocs-meterial](https://squidfunk.github.io/mkdocs-material/) with some plugins embeded.
+
+Usage
+
+Mount the folder where your mkdocs.yml resides as a volume into /docs:
+
+- Start development server on http://localhost:8000
+
+```console
+docker run --rm -it -p 8000:8000 -v ${PWD}:/docs sagewei0/mkdocs
+```
+
+- Build documentation
+
+```console
+docker run --rm -it -v ${PWD}:/docs sagewei/mkdocs build
+```
+
+- Deploy documentation to GitHub Pages
+
+```console
+docker run --rm -it -v ~/.ssh:/root/.ssh -v ${PWD}:/docs sagewei0/mkdocs gh-deploy 
+```