You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@opendal.apache.org by er...@apache.org on 2025/05/12 19:25:25 UTC

(opendal) 02/03: doc(bindings/python): service page template and generation

This is an automated email from the ASF dual-hosted git repository.

erickguan pushed a commit to branch docs-service-website
in repository https://gitbox.apache.org/repos/asf/opendal.git

commit 7183272a60cafbb431b91b3ee7f1f9ae2457acb1
Author: Erick Guan <29...@users.noreply.github.com>
AuthorDate: Sun May 11 20:00:23 2025 +0200

    doc(bindings/python): service page template and generation
---
 bindings/python/docs/SUMMARY.md                    |  1 +
 dev/src/generate/python-mkdocs-service-summary.j2  | 20 ++++++++++
 dev/src/generate/python-mkdocs-service.j2          | 27 ++++++++++++++
 .../generate/{python.j2 => python-type-hints.j2}   |  0
 dev/src/generate/python.rs                         | 43 +++++++++++++++++++---
 5 files changed, 86 insertions(+), 5 deletions(-)

diff --git a/bindings/python/docs/SUMMARY.md b/bindings/python/docs/SUMMARY.md
index dab52f1fc..aea7c767a 100644
--- a/bindings/python/docs/SUMMARY.md
+++ b/bindings/python/docs/SUMMARY.md
@@ -3,6 +3,7 @@
     - [Basic](examples/basic.ipynb)
     - [Pandas](examples/pandas.ipynb)
     - [Polars](examples/polars.ipynb)
+- [Services](services/)
 - API Reference
     - [Operator](api/operator.md)
     - [File](api/file.md)
diff --git a/dev/src/generate/python-mkdocs-service-summary.j2 b/dev/src/generate/python-mkdocs-service-summary.j2
new file mode 100644
index 000000000..33d278cb6
--- /dev/null
+++ b/dev/src/generate/python-mkdocs-service-summary.j2
@@ -0,0 +1,20 @@
+{# Licensed to the Apache Software Foundation (ASF) under one
+ # or more contributor license agreements.  See the NOTICE file
+ # distributed with this work for additional information
+ # regarding copyright ownership.  The ASF licenses this file
+ # to you under the Apache License, Version 2.0 (the
+ # "License"); you may not use this file except in compliance
+ # with the License.  You may obtain a copy of the License at
+ #
+ #   http://www.apache.org/licenses/LICENSE-2.0
+ #
+ # Unless required by applicable law or agreed to in writing,
+ # software distributed under the License is distributed on an
+ # "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ # KIND, either express or implied.  See the License for the
+ # specific language governing permissions and limitations
+ # under the License. #}
+
+{%- for name, service in services|items %}
+- [`{{name}}`]({{name}}.md)
+{%- endfor %}
diff --git a/dev/src/generate/python-mkdocs-service.j2 b/dev/src/generate/python-mkdocs-service.j2
new file mode 100644
index 000000000..9f6119f4f
--- /dev/null
+++ b/dev/src/generate/python-mkdocs-service.j2
@@ -0,0 +1,27 @@
+{# Licensed to the Apache Software Foundation (ASF) under one
+ # or more contributor license agreements.  See the NOTICE file
+ # distributed with this work for additional information
+ # regarding copyright ownership.  The ASF licenses this file
+ # to you under the Apache License, Version 2.0 (the
+ # "License"); you may not use this file except in compliance
+ # with the License.  You may obtain a copy of the License at
+ #
+ #   http://www.apache.org/licenses/LICENSE-2.0
+ #
+ # Unless required by applicable law or agreed to in writing,
+ # software distributed under the License is distributed on an
+ # "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ # KIND, either express or implied.  See the License for the
+ # specific language governing permissions and limitations
+ # under the License. -#}
+
+## {{name | split('_') | map('capitalize') | join }}Config
+
+{% for field in service.config -%}
+
+### `{{field.name}}`: `{{make_python_type(field.value)}}`
+
+{% if field.deprecated %}**deprecated**: {{field.deprecated["note"]}}{% endif -%}
+{{field.comments}}
+
+{% endfor %}
diff --git a/dev/src/generate/python.j2 b/dev/src/generate/python-type-hints.j2
similarity index 100%
rename from dev/src/generate/python.j2
rename to dev/src/generate/python-type-hints.j2
diff --git a/dev/src/generate/python.rs b/dev/src/generate/python.rs
index 79add9634..030f9b7ea 100644
--- a/dev/src/generate/python.rs
+++ b/dev/src/generate/python.rs
@@ -25,23 +25,56 @@ use std::path::PathBuf;
 fn enabled_service(srv: &str) -> bool {
     match srv {
         // not enabled in bindings/python/Cargo.toml
-        "etcd" | "foundationdb" | "ftp" | "hdfs" | "rocksdb" | "tikv" => false,
+        "etcd" | "foundationdb" | "ftp" | "hdfs" | "hdfs-native" | "rocksdb" | "tikv" => false,
         _ => true,
     }
 }
 
 pub fn generate(workspace_dir: PathBuf, services: Services) -> Result<()> {
+    let env = setup_environment()?;
     let services = sorted_services(services, enabled_service);
-    let mut env = Environment::new();
-    env.add_template("python", include_str!("python.j2"))?;
-    env.add_function("make_python_type", make_python_type);
-    let template = env.get_template("python")?;
 
+    generate_typing_hints(&env, &workspace_dir, &services)?;
+    generate_mkdocs(&env, &workspace_dir, &services)?;
+    Ok(())
+}
+
+/// Generates Python typing hints
+fn generate_typing_hints(env: &Environment, workspace_dir: &PathBuf, services: &Services) -> Result<()> {
+    let template = env.get_template("python-type-hints")?;
     let output = workspace_dir.join("bindings/python/python/opendal/__base.pyi");
     fs::write(output, template.render(context! { services => services })?)?;
     Ok(())
 }
 
+/// Generates service documentations for mkdocs website.
+fn generate_mkdocs(env: &Environment, workspace_dir: &PathBuf, services: &Services) -> Result<()> {
+    let template = env.get_template("python-mkdocs-service")?;
+    let output_folder = workspace_dir.join("bindings/python/docs/services/");
+    fs::remove_dir_all(&output_folder)?;
+    fs::create_dir(&output_folder)?;
+
+    for (name, service) in services.iter() {
+        let path = output_folder.join(format!("{}.md", name));
+        fs::write(path, template.render(context! { name => name, service => service })?)?;
+    }
+
+    let template = env.get_template("python-mkdocs-service-summary")?;
+    fs::write(output_folder.join("SUMMARY.md"), template.render(context! { services => services })?)?;
+    Ok(())
+}
+
+/// Creates `Environment` for rendering
+fn setup_environment() -> Result<Environment<'static>> { // includes static template strings
+    let mut env = Environment::new();
+    env.add_template("python-type-hints", include_str!("python-type-hints.j2"))?;
+    // #5457 discussed a better approach generating config types when PyO3 can generate stubs when compiling.
+    env.add_template("python-mkdocs-service", include_str!("python-mkdocs-service.j2"))?;
+    env.add_template("python-mkdocs-service-summary", include_str!("python-mkdocs-service-summary.j2"))?;
+    env.add_function("make_python_type", make_python_type);
+    Ok(env)
+}
+
 fn make_python_type(ty: ViaDeserialize<ConfigType>) -> Result<String, minijinja::Error> {
     Ok(match ty.0 {
         ConfigType::Bool => "_bool",