Pre-render Mermaid diagrams (kedro-org#3449)

* Pre-render Mermaid diagrams Signed-off-by: Juan Luis Cano Rodríguez <[email protected]> * Remove use of sphinxcontrib-mermaid Fix kedro-orggh-3395. Signed-off-by: Juan Luis Cano Rodríguez <[email protected]> * Add rendering instructions for Mermaid diagrams Signed-off-by: Juan Luis Cano Rodríguez <[email protected]> --------- Signed-off-by: Juan Luis Cano Rodríguez <[email protected]>
HOZHENWAI · Dec 20, 2023 · b11666e · b11666e
1 parent e190b3a
commit b11666e
Show file tree

Hide file tree

Showing 12 changed files with 65 additions and 73 deletions.
diff --git a/.gitpod.Dockerfile b/.gitpod.Dockerfile
@@ -7,7 +7,6 @@ RUN pyenv install 3.8.15\
 # VideoDataset
 RUN sudo apt-get update && sudo apt-get install -y --no-install-recommends libgl1
 RUN sudo apt-get install make
-RUN npm install -g @mermaid-js/mermaid-cli
 # https://stackoverflow.com/questions/69564238/puppeteer-error-failed-to-launch-the-browser-process
 # https://github.com/puppeteer/puppeteer/blob/main/docs/troubleshooting.md#chrome-doesnt-launch-on-linux
 RUN sudo apt-get install -y --no-install-recommends libatk-bridge2.0-0 libcups2 ca-certificates fonts-liberation libasound2 libatk-bridge2.0-0 libatk1.0-0 libc6 libcairo2 libcups2 libdbus-1-3 libexpat1 libfontconfig1 libgbm1 libgcc1 libglib2.0-0 libgtk-3-0 libnspr4 libnss3 libpango-1.0-0 libpangocairo-1.0-0 libstdc++6 libx11-6 libx11-xcb1 libxcb1 libxcomposite1 libxcursor1 libxdamage1 libxext6 libxfixes3 libxi6 libxrandr2 libxrender1 libxss1 libxtst6 lsb-release wget xdg-utils
diff --git a/.readthedocs.yml b/.readthedocs.yml
@@ -10,11 +10,7 @@ build:
  tools:
  python: "3.9"
  nodejs: "19"
- apt_packages:
- - libasound2
  jobs:
- post_create_environment:
- - npm install -g @mermaid-js/mermaid-cli
  pre_build:
  - pip freeze
  - python -m sphinx -WETan -j auto -D language=en -b linkcheck -d _build/doctrees docs/source _build/linkcheck

diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -50,7 +50,6 @@
  "sphinx.ext.ifconfig",
  "sphinx.ext.viewcode",
  "sphinx_copybutton",
- "sphinxcontrib.mermaid",
  "myst_parser",
  "notfound.extension",
  "sphinxcontrib.jquery",
@@ -546,11 +545,3 @@ def setup(app):
 user_agent = "Mozilla/5.0 (X11; Linux x86_64; rv:99.0) Gecko/20100101 Firefox/99.0"
 
 myst_heading_anchors = 5
-
-# https://github.com/kedro-org/kedro/issues/1772
-mermaid_output_format = "png"
-# https://github.com/mermaidjs/mermaid.cli#linux-sandbox-issue
-# https://github.com/mermaid-js/mermaid-cli/issues/544
-mermaid_params = ["-p", here / "puppeteer-config.json", "-s", "2"]
-# https://github.com/kedro-org/kedro/issues/2451
-mermaid_version = mermaid_init_js = ""
diff --git a/docs/source/deployment/databricks/index.md b/docs/source/deployment/databricks/index.md
@@ -24,21 +24,23 @@ The workflow documented in ["Use a Databricks job to deploy a Kedro project"](./
 ---
 Here's a flowchart to guide your choice of workflow:
 
-```{mermaid}
+```{image} ../../meta/images/databricks-flow-chart.png
 :alt: mermaid-Decision making diagram for deploying Kedro projects to Databricks
-
-flowchart TD
- A[Start] --> B{Do you prefer developing your projects in notebooks?}
- B -->|Yes| C[Use a Databricks workspace to develop a Kedro project]
- B -->|No| D{Are you a beginner with Kedro?}
- D -->|Yes| E[Use an IDE, dbx and Databricks Repos to develop a Kedro project]
- D -->|No| F{Do you have advanced project requirements<br>e.g. CI/CD, scheduling, production-ready, complex pipelines, etc.?}
- F -->|Yes| G{Is rapid development needed for your project needs?}
- F -->|No| H[Use an IDE, dbx and Databricks Repos to develop a Kedro project]
- G -->|Yes| I[Use an IDE, dbx and Databricks Repos to develop a Kedro project]
- G -->|No| J[Use a Databricks job to deploy a Kedro project]
 ```
 
+% Mermaid code, see https://github.com/kedro-org/kedro/wiki/Render-Mermaid-diagrams
+% flowchart TD
+% A[Start] --> B{Do you prefer developing your projects in notebooks?}
+% B -->|Yes| C[Use a Databricks workspace to develop a Kedro project]
+% B -->|No| D{Are you a beginner with Kedro?}
+% D -->|Yes| E[Use an IDE, dbx and Databricks Repos to develop a Kedro project]
+% D -->|No| F{Do you have advanced project requirements<br>e.g. CI/CD, scheduling, production-ready, complex pipelines, etc.?}
+% F -->|Yes| G{Is rapid development needed for your project needs?}
+% F -->|No| H[Use an IDE, dbx and Databricks Repos to develop a Kedro project]
+% G -->|Yes| I[Use an IDE, dbx and Databricks Repos to develop a Kedro project]
+% G -->|No| J[Use a Databricks job to deploy a Kedro project]
+
+
 Remember, the best choice of workflow is the one that aligns best with your project's requirements, whether that's quick development, notebook-based coding, or a production-ready setup. Make sure to consider these factors alongside your comfort level with Kedro when making your decision.
 
 

diff --git a/docs/source/deployment/index.md b/docs/source/deployment/index.md
@@ -10,19 +10,20 @@ If you decide to deploy your Kedro project onto a single machine, you should con
 
 If your pipeline is sizeable, you may want to run it across separate machines, so will need to consult our [guide to distributed deployment](distributed.md).
 
-```{mermaid}
+```{image} ../meta/images/deployment-diagram.png
 :alt: mermaid-Decision making diagram for deploying Kedro projects
-
-flowchart TD
- A{Can your Kedro pipeline run on a single machine?} -- YES --> B[Consult the single-machine deployment guide];
- B --> C{Do you have Docker on your machine?};
- C -- YES --> D[Use a container-based approach];
- C -- NO --> E[Use the CLI or package mode];
- A -- NO --> F[Consult the distributed deployment guide];
- F --> G["What distributed platform are you using?<br/><br/>Check out the guides for:<br/><br/><li>Airflow</li><li>Amazon SageMaker</li><li>AWS Step functions</li><li>Azure</li><li>Dask</li><li>Databricks</li><li>Kubeflow Workflows</li><li>Prefect</li><li>Vertex AI</li>"];
- style G text-align:left
 ```
 
+% Mermaid code, see https://github.com/kedro-org/kedro/wiki/Render-Mermaid-diagrams
+% flowchart TD
+% A{Can your Kedro pipeline run on a single machine?} -- YES --> B[Consult the single-machine deployment guide];
+% B --> C{Do you have Docker on your machine?};
+% C -- YES --> D[Use a container-based approach];
+% C -- NO --> E[Use the CLI or package mode];
+% A -- NO --> F[Consult the distributed deployment guide];
+% F --> G["What distributed platform are you using?<br/><br/>Check out the guides for:<br/><br/><li>Airflow</li><li>Amazon SageMaker</li><li>AWS Step functions</li><li>Azure</li><li>Dask</li><li>Databricks</li><li>Kubeflow Workflows</li><li>Prefect</li><li>Vertex AI</li>"];
+% style G text-align:left
+
 This following pages provide information for deployment to, or integration with, the following:
 
 * [Airflow](airflow_astronomer.md)

diff --git a/docs/source/get_started/new_project.md b/docs/source/get_started/new_project.md
@@ -104,20 +104,22 @@ If you've worked through the documentation listed and are unsure where to go nex
 
 Here is a flowchart to help guide your choice of tools and examples you can select:
 
-```{mermaid}
-:alt: General overview diagram for setting up a new Kedro project with tools
-flowchart TD
- A[Start] --> B[Enter Project Name];
- B --> C[Select Tools];
-
- C -->|None| D[None];
- C -->|Any combination| E[lint, test, logging, docs, data, PySpark, viz];
- C -->|All| F[All];
-
- D --> G[Include Example Pipeline?]
- E --> G;
- F --> G
-
- G -->|Yes| H[New Project Created];
- G -->|No| H;
+```{figure} ../meta/images/new-project-tools.png
+:alt: mermaid-General overview diagram for setting up a new Kedro project with tools
 ```
+
+% Mermaid code, see https://github.com/kedro-org/kedro/wiki/Render-Mermaid-diagrams
+% flowchart TD
+% A[Start] --> B[Enter Project Name];
+% B --> C[Select Tools];
+%
+% C -->|None| D[None];
+% C -->|Any combination| E[lint, test, logging, docs, data, PySpark, viz];
+% C -->|All| F[All];
+%
+% D --> G[Include Example Pipeline?]
+% E --> G;
+% F --> G
+%
+% G -->|Yes| H[New Project Created];
+% G -->|No| H;
diff --git a/docs/source/meta/images/databricks-flow-chart.png b/docs/source/meta/images/databricks-flow-chart.png
diff --git a/docs/source/meta/images/deployment-diagram.png b/docs/source/meta/images/deployment-diagram.png
diff --git a/docs/source/meta/images/new-project-tools.png b/docs/source/meta/images/new-project-tools.png
diff --git a/docs/source/meta/images/project-tools-choices.png b/docs/source/meta/images/project-tools-choices.png
diff --git a/docs/source/starters/new_project_tools.md b/docs/source/starters/new_project_tools.md
@@ -259,24 +259,26 @@ See the [Kedro-Viz documentation](https://docs.kedro.org/projects/kedro-viz/en/s
 
 Here is a flowchart to help illustrate some example choice of tools you can select:
 
-```{mermaid}
-:alt: Example diagram of specific tool choices
-flowchart TD
- A[Start] --> B[Enter Project Name: Example Project];
- B --> C3[Select Tools: None];
- B --> C1[Select Tools: lint, docs, PySpark];
- B --> C2[Select Tools: All];
-
- C1 --> D1[Include Example Pipeline?];
- C2 --> D2[Include Example Pipeline?];
- C3 --> D3[Include Example Pipeline?];
-
- D1 -->|Yes| E1[New Project Created\nName: Example Project\nTools: lint, docs, PySpark\nExample: Yes];
- D1 -->|No| E2[New Project Created\nName: Example Project\nTools: lint, docs, PySpark\nExample: No];
-
- D2 -->|Yes| F1[New Project Created\nName: Example Project\nTools: All: lint, test, logging, docs, data, PySpark, viz \nExample: Yes];
- D2 -->|No| F2[New Project Created\nName: Example Project\nTools: All: lint, test, logging, docs, data, PySpark, viz \nExample: No];
-
- D3 -->|Yes| G1[New Project Created\nName: Example Project\nTools: None\nExample: Yes];
- D3 -->|No| G2[New Project Created\nName: Example Project\nTools: None\nExample: No];
+```{image} ../meta/images/project-tools-choices.png
+:alt: mermaid-Example diagram of specific tool choices
 ```
+
+% Mermaid code, see https://github.com/kedro-org/kedro/wiki/Render-Mermaid-diagrams
+% flowchart TD
+% A[Start] --> B[Enter Project Name: Example Project];
+% B --> C3[Select Tools: None];
+% B --> C1[Select Tools: lint, docs, PySpark];
+% B --> C2[Select Tools: All];
+%
+% C1 --> D1[Include Example Pipeline?];
+% C2 --> D2[Include Example Pipeline?];
+% C3 --> D3[Include Example Pipeline?];
+%
+% D1 -->|Yes| E1[New Project Created\nName: Example Project\nTools: lint, docs, PySpark\nExample: Yes];
+% D1 -->|No| E2[New Project Created\nName: Example Project\nTools: lint, docs, PySpark\nExample: No];
+%
+% D2 -->|Yes| F1[New Project Created\nName: Example Project\nTools: All: lint, test, logging, docs, data, PySpark, viz \nExample: Yes];
+% D2 -->|No| F2[New Project Created\nName: Example Project\nTools: All: lint, test, logging, docs, data, PySpark, viz \nExample: No];
+%
+% D3 -->|Yes| G1[New Project Created\nName: Example Project\nTools: None\nExample: Yes];
+% D3 -->|No| G2[New Project Created\nName: Example Project\nTools: None\nExample: No];
diff --git a/pyproject.toml b/pyproject.toml
@@ -94,7 +94,6 @@ docs = [
  "sphinx_copybutton==0.3.1",
  "sphinx-notfound-page",
  "ipykernel>=5.3, <7.0",
- "sphinxcontrib-mermaid~=0.7.1",
  "myst-parser~=1.0.0",
  "Jinja2<3.1.0",
 ]