You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@iceberg.apache.org by fo...@apache.org on 2023/04/24 08:03:15 UTC
[iceberg] branch master updated: Python: Add mkdocstrings (#7108)
This is an automated email from the ASF dual-hosted git repository.
fokko pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/iceberg.git
The following commit(s) were added to refs/heads/master by this push:
new 6a111717a0 Python: Add mkdocstrings (#7108)
6a111717a0 is described below
commit 6a111717a0fede21d9993d8c9d12f992f04eb634
Author: Luigi Cerone <lu...@gmail.com>
AuthorDate: Mon Apr 24 10:03:09 2023 +0200
Python: Add mkdocstrings (#7108)
* Add mkdocstrings
* Add mkdocs theme
* Add theme to mkdocs and fix pages gen
* Fix missing license
* Fix prettier
---
python/.pre-commit-config.yaml | 2 +
python/mkdocs/docs/SUMMARY.md | 31 ++++++++++++
python/mkdocs/docs/api.md | 5 ++
.../docs/assets/images/iceberg-logo-icon.png | Bin 0 -> 17608 bytes
python/mkdocs/docs/cli.md | 5 ++
python/mkdocs/docs/configuration.md | 5 ++
python/mkdocs/docs/contributing.md | 5 ++
python/mkdocs/docs/feature-support.md | 5 ++
python/mkdocs/docs/index.md | 5 ++
python/mkdocs/gen_doc_stubs.py | 55 +++++++++++++++++++++
python/mkdocs/mkdocs.yml | 47 +++++++++++++-----
python/mkdocs/requirements.txt | 9 ++++
12 files changed, 162 insertions(+), 12 deletions(-)
diff --git a/python/.pre-commit-config.yaml b/python/.pre-commit-config.yaml
index d6642ff87c..2abac29d27 100644
--- a/python/.pre-commit-config.yaml
+++ b/python/.pre-commit-config.yaml
@@ -82,3 +82,5 @@ repos:
- mdformat-config
- mdformat-beautysh
- mdformat-admon
+ - mdformat-mkdocs
+ - mdformat-frontmatter
diff --git a/python/mkdocs/docs/SUMMARY.md b/python/mkdocs/docs/SUMMARY.md
new file mode 100644
index 0000000000..46383823ec
--- /dev/null
+++ b/python/mkdocs/docs/SUMMARY.md
@@ -0,0 +1,31 @@
+<!--
+ - 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.
+ -->
+
+<!-- prettier-ignore-start -->
+
+- [Home](index.md)
+- [Configuration](configuration.md)
+- [CLI](cli.md)
+- [API](api.md)
+- [Contributing](contributing.md)
+- [Feature support](feature-support.md)
+- Releases
+ - [Verify a release](verify-release.md)
+ - [How to release](how-to-release.md)
+- [Code Reference](reference/)
+
+<!-- prettier-ignore-end -->
diff --git a/python/mkdocs/docs/api.md b/python/mkdocs/docs/api.md
index bd6b3d3d6f..ddd5ca180f 100644
--- a/python/mkdocs/docs/api.md
+++ b/python/mkdocs/docs/api.md
@@ -1,3 +1,8 @@
+---
+hide:
+ - navigation
+---
+
<!--
- Licensed to the Apache Software Foundation (ASF) under one
- or more contributor license agreements. See the NOTICE file
diff --git a/python/mkdocs/docs/assets/images/iceberg-logo-icon.png b/python/mkdocs/docs/assets/images/iceberg-logo-icon.png
new file mode 100644
index 0000000000..e4a99c3951
Binary files /dev/null and b/python/mkdocs/docs/assets/images/iceberg-logo-icon.png differ
diff --git a/python/mkdocs/docs/cli.md b/python/mkdocs/docs/cli.md
index 5b760e1fa6..695011a6ef 100644
--- a/python/mkdocs/docs/cli.md
+++ b/python/mkdocs/docs/cli.md
@@ -1,3 +1,8 @@
+---
+hide:
+ - navigation
+---
+
<!--
- Licensed to the Apache Software Foundation (ASF) under one
- or more contributor license agreements. See the NOTICE file
diff --git a/python/mkdocs/docs/configuration.md b/python/mkdocs/docs/configuration.md
index 60d46fba44..65a3fdad43 100644
--- a/python/mkdocs/docs/configuration.md
+++ b/python/mkdocs/docs/configuration.md
@@ -1,3 +1,8 @@
+---
+hide:
+ - navigation
+---
+
<!--
- Licensed to the Apache Software Foundation (ASF) under one
- or more contributor license agreements. See the NOTICE file
diff --git a/python/mkdocs/docs/contributing.md b/python/mkdocs/docs/contributing.md
index 47bc4421d6..bf6f12872d 100644
--- a/python/mkdocs/docs/contributing.md
+++ b/python/mkdocs/docs/contributing.md
@@ -1,3 +1,8 @@
+---
+hide:
+ - navigation
+---
+
<!--
- Licensed to the Apache Software Foundation (ASF) under one
- or more contributor license agreements. See the NOTICE file
diff --git a/python/mkdocs/docs/feature-support.md b/python/mkdocs/docs/feature-support.md
index d562a0065c..9c466c9337 100644
--- a/python/mkdocs/docs/feature-support.md
+++ b/python/mkdocs/docs/feature-support.md
@@ -1,3 +1,8 @@
+---
+hide:
+ - navigation
+---
+
<!--
- Licensed to the Apache Software Foundation (ASF) under one or more
- contributor license agreements. See the NOTICE file distributed with
diff --git a/python/mkdocs/docs/index.md b/python/mkdocs/docs/index.md
index 2f739d6afd..36fb656fca 100644
--- a/python/mkdocs/docs/index.md
+++ b/python/mkdocs/docs/index.md
@@ -1,3 +1,8 @@
+---
+hide:
+ - navigation
+---
+
<!--
- Licensed to the Apache Software Foundation (ASF) under one or more
- contributor license agreements. See the NOTICE file distributed with
diff --git a/python/mkdocs/gen_doc_stubs.py b/python/mkdocs/gen_doc_stubs.py
new file mode 100644
index 0000000000..bd3b128101
--- /dev/null
+++ b/python/mkdocs/gen_doc_stubs.py
@@ -0,0 +1,55 @@
+# 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.
+
+from pathlib import Path
+
+import griffe # type: ignore
+import mkdocs_gen_files # type: ignore
+
+nav = mkdocs_gen_files.Nav()
+
+root = Path(__file__).parent.parent
+src_root = root.joinpath("pyiceberg")
+
+data = griffe.load(src_root)
+for path in sorted(src_root.glob("**/*.py")):
+ module_path = path.relative_to(root).with_suffix("")
+ doc_path = path.relative_to(root).with_suffix(".md")
+ full_doc_path = Path("reference", doc_path)
+
+ parts = tuple(module_path.parts)
+
+ if parts[-1] == "__init__":
+ parts = parts[:-1]
+ doc_path = doc_path.with_name("index.md")
+ full_doc_path = full_doc_path.with_name("index.md")
+ elif parts[-1].startswith("_"):
+ continue
+
+ if module_path.parts[1:] in data.members and not data[module_path.parts[1:]].has_docstrings:
+ continue
+
+ nav[parts] = doc_path.as_posix()
+
+ with mkdocs_gen_files.open(full_doc_path, "w") as fd:
+ ident = ".".join(parts)
+ fd.write(f"::: {ident}")
+
+ mkdocs_gen_files.set_edit_path(full_doc_path, Path("../") / path)
+
+with mkdocs_gen_files.open("reference/SUMMARY.md", "w") as nav_file:
+ nav_file.writelines(nav.build_literate_nav())
diff --git a/python/mkdocs/mkdocs.yml b/python/mkdocs/mkdocs.yml
index d9904da21d..6040f00ebe 100644
--- a/python/mkdocs/mkdocs.yml
+++ b/python/mkdocs/mkdocs.yml
@@ -17,18 +17,41 @@
---
site_name: PyIceberg
site_url: https://py.iceberg.apache.org/
-nav:
- - Home: index.md
- - Configuration: configuration.md
- - CLI: cli.md
- - API: api.md
- - Contributing:
- - Contributing: contributing.md
- - Feature support: feature-support.md
- - Releases:
- - Verify a release: verify-release.md
- - How to release: how-to-release.md
+repo_url: "https://github.com/apache/iceberg/tree/master/python"
+repo_name: "apache/iceberg/python"
+
+plugins:
+ - gen-files:
+ scripts:
+ - gen_doc_stubs.py
+ - literate-nav:
+ nav_file: SUMMARY.md
+ - search
+ - section-index
+ - mkdocstrings:
+ handlers:
+ python:
+ paths: [..]
+
theme:
- name: readthedocs
+ name: material
+ logo: assets/images/iceberg-logo-icon.png
+ favicon: assets/images/iceberg-logo-icon.png
+ font:
+ text: Lato
+ features:
+ - navigation.top
+ - navigation.tracking
+ - navigation.tabs
+ - navigation.tabs.sticky
+ palette:
+ - scheme: default
+ toggle:
+ icon: material/brightness-7
+ name: Switch to dark mode
+ - scheme: slate
+ toggle:
+ icon: material/brightness-4
+ name: Switch to light mode
markdown_extensions:
- admonition
diff --git a/python/mkdocs/requirements.txt b/python/mkdocs/requirements.txt
index 143c4cacfb..433580a22d 100644
--- a/python/mkdocs/requirements.txt
+++ b/python/mkdocs/requirements.txt
@@ -16,4 +16,13 @@
# under the License.
mkdocs==1.4.2
+griffe==0.26.0
jinja2==3.1.2
+mkdocstrings==0.20.0
+mkdocstrings-python==0.8.3
+mkdocs-literate-nav==0.6.0
+mkdocs-autorefs==0.4.1
+mkdocs-gen-files==0.4.0
+mkdocs-material==9.1.5
+mkdocs-material-extensions==1.1.1
+mkdocs-section-index==0.3.5