From b5f7fa8dcafe0ef1f305e8e52bedd24233cf296e Mon Sep 17 00:00:00 2001 From: Xi Xu Date: Fri, 6 Jun 2025 17:50:43 +0800 Subject: [PATCH] Enhance documentation with SEO metadata and layout Added a new custom layout template for SEO and social media meta tags. Updated multiple documentation files with metadata for improved search engine optimization and social sharing. Enhanced Sphinx configuration with additional HTML options and meta tags. --- docs/_templates/layout.html | 45 +++++++++++++++++++++++++++++++++++++ docs/api/cli.md | 10 +++++++++ docs/api/core.md | 10 +++++++++ docs/api/exceptions.md | 13 +++++++++++ docs/api/index.md | 10 +++++++++ docs/conf.py | 38 +++++++++++++++++++++++++++++-- docs/examples.md | 10 +++++++++ docs/index.md | 10 +++++++++ docs/quickstart.md | 10 +++++++++ 9 files changed, 154 insertions(+), 2 deletions(-) create mode 100644 docs/_templates/layout.html diff --git a/docs/_templates/layout.html b/docs/_templates/layout.html new file mode 100644 index 0000000..d48b28f --- /dev/null +++ b/docs/_templates/layout.html @@ -0,0 +1,45 @@ +{% extends "!layout.html" %} + +{% block extrahead %} + {{ super() }} + + + + + + + + + {% if pagename != 'index' %} + + {% else %} + + {% endif %} + + + + +{% endblock %} diff --git a/docs/api/cli.md b/docs/api/cli.md index 16de7b4..18e556e 100644 --- a/docs/api/cli.md +++ b/docs/api/cli.md @@ -1,3 +1,13 @@ +--- +html_meta: + description: "tzst CLI API - Command-line interface functions and utilities for tar.zst archive operations" + keywords: "tzst CLI API, command line interface, Python CLI, tar.zst commands" + og:title: "tzst CLI API Reference" + og:description: "CLI API documentation for tzst - Command-line interface functions and utilities" + twitter:title: "tzst CLI API Reference" + twitter:description: "CLI API documentation for tzst - Command-line interface functions and utilities" +--- + # CLI API The command-line interface module provides comprehensive functionality for the tzst CLI tool, including argument parsing, command execution, and interactive features. diff --git a/docs/api/core.md b/docs/api/core.md index 368bac7..29e5dc6 100644 --- a/docs/api/core.md +++ b/docs/api/core.md @@ -1,3 +1,13 @@ +--- +html_meta: + description: "tzst Core API - TzstArchive class and convenience functions for tar.zst archive operations" + keywords: "tzst core API, TzstArchive, Python archive class, tar.zst functions" + og:title: "tzst Core API Reference" + og:description: "Core API documentation for tzst - TzstArchive class and convenience functions" + twitter:title: "tzst Core API Reference" + twitter:description: "Core API documentation for tzst - TzstArchive class and convenience functions" +--- + # Core API The core module provides the main functionality for working with tzst archives, including the primary `TzstArchive` class and high-level convenience functions. diff --git a/docs/api/exceptions.md b/docs/api/exceptions.md index 9b2d07e..de5a76f 100644 --- a/docs/api/exceptions.md +++ b/docs/api/exceptions.md @@ -1,3 +1,16 @@ +--- +html_meta: + description: "Complete reference for tzst exception classes and error handling. Learn about TzstError, TzstArchiveError, and other custom exceptions for robust archive operations." + keywords: "tzst exceptions, Python exceptions, error handling, TzstError, TzstArchiveError, archive errors, compression errors" + "og:title": "tzst Exceptions API Reference" + "og:description": "Complete reference for tzst exception classes and error handling. Learn about TzstError, TzstArchiveError, and other custom exceptions for robust archive operations." + "og:type": "article" + "twitter:title": "tzst Exceptions API Reference" + "twitter:description": "Complete reference for tzst exception classes and error handling. Learn about TzstError, TzstArchiveError, and other custom exceptions for robust archive operations." + "article:section": "API Reference" + "article:tag": "exceptions, error handling, API" +--- + # Exceptions API Custom exception classes used by tzst for comprehensive error handling and debugging. diff --git a/docs/api/index.md b/docs/api/index.md index e8e6d79..dfac73e 100644 --- a/docs/api/index.md +++ b/docs/api/index.md @@ -1,3 +1,13 @@ +--- +html_meta: + description: "Complete tzst API reference - Core functions, CLI tools, and exception handling for tar.zst archives" + keywords: "tzst API, Python API documentation, tar.zst API reference, archive API" + og:title: "tzst API Reference" + og:description: "Complete API reference for tzst - Core functions, CLI tools, and exception handling" + twitter:title: "tzst API Reference" + twitter:description: "Complete API reference for tzst - Core functions, CLI tools, and exception handling" +--- + # API Reference This section contains the complete API documentation for tzst, providing detailed information about classes, functions, and exceptions. diff --git a/docs/conf.py b/docs/conf.py index b1df13a..f01349f 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -35,6 +35,27 @@ html_static_path = ["_static"] html_title = f"tzst {version} Documentation" html_short_title = "tzst" +# HTML meta tags +html_meta = { + "description": "tzst - A Python library for creating and extracting tar.zst archives with high performance and comprehensive features", + "keywords": "tzst, tar, zstandard, compression, archive, python, extraction, backup", + "author": "Xi Xu", + "robots": "index, follow", + "language": "en", + "viewport": "width=device-width, initial-scale=1.0", + "theme-color": "#2980B9", + "msapplication-TileColor": "#2980B9", + "og:title": "tzst Documentation", + "og:description": "tzst - A Python library for creating and extracting tar.zst archives with high performance and comprehensive features", + "og:type": "website", + "og:url": "https://xixu-me.github.io/tzst/", + "og:image": "https://xixu-me.github.io/tzst/_static/tzst-logo.png", + "twitter:card": "summary_large_image", + "twitter:title": "tzst Documentation", + "twitter:description": "tzst - A Python library for creating and extracting tar.zst archives with high performance and comprehensive features", + "twitter:image": "https://xixu-me.github.io/tzst/_static/tzst-logo.png", +} + # Theme options html_theme_options = { "canonical_url": "https://xixu-me.github.io/tzst/", @@ -45,8 +66,21 @@ html_theme_options = { "collapse_navigation": True, "sticky_navigation": True, "navigation_depth": 4, - "includehidden": True, - "titles_only": False, + "includehidden": True, "titles_only": False, +} + +# Additional HTML options +html_favicon = "_static/favicon.ico" # Will show warning until favicon is created +html_logo = "_static/tzst-logo.png" # Will show warning until logo is created +html_use_opensearch = "https://xixu-me.github.io/tzst/" + +# HTML context for custom template variables +html_context = { + "display_github": True, + "github_user": "xixu-me", + "github_repo": "tzst", + "github_version": "main", + "conf_py_path": "/docs/", } # -- Extension configuration ------------------------------------------------- diff --git a/docs/examples.md b/docs/examples.md index 9b0259f..e40422d 100644 --- a/docs/examples.md +++ b/docs/examples.md @@ -1,3 +1,13 @@ +--- +html_meta: + description: "Comprehensive tzst examples - Learn advanced archive creation, extraction, security, and performance optimization" + keywords: "tzst examples, Python archive examples, tar.zst tutorials, Zstandard compression examples" + og:title: "tzst Examples and Tutorials" + og:description: "Comprehensive examples for tzst - archive creation, extraction, security, and performance optimization" + twitter:title: "tzst Examples and Tutorials" + twitter:description: "Comprehensive examples for tzst - archive creation, extraction, security, and performance optimization" +--- + # Examples This section provides comprehensive examples of using tzst for various scenarios and use cases. diff --git a/docs/index.md b/docs/index.md index ef06b58..8dab12d 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,3 +1,13 @@ +--- +html_meta: + description: "tzst - Next-generation Python library for tar.zst archives with Zstandard compression. Fast, secure, and reliable archive management." + keywords: "tzst, Python, tar.zst, Zstandard, compression, archive, backup, file management" + og:title: "tzst - Next-Generation Archive Management" + og:description: "Fast, secure, and reliable Python library for tar.zst archives with Zstandard compression" + twitter:title: "tzst - Next-Generation Archive Management" + twitter:description: "Fast, secure, and reliable Python library for tar.zst archives with Zstandard compression" +--- + # tzst Documentation Welcome to **tzst**, the next-generation Python library engineered for modern archive management, leveraging cutting-edge Zstandard compression to deliver superior performance, security, and reliability. diff --git a/docs/quickstart.md b/docs/quickstart.md index 3da64e9..589f9d2 100644 --- a/docs/quickstart.md +++ b/docs/quickstart.md @@ -1,3 +1,13 @@ +--- +html_meta: + description: "Quick start guide for tzst - Learn how to install and use the Python tar.zst archive library in minutes" + keywords: "tzst tutorial, Python archive tutorial, tar.zst guide, Zstandard compression guide" + og:title: "tzst Quick Start Guide" + og:description: "Learn how to install and use tzst for Python tar.zst archive management in minutes" + twitter:title: "tzst Quick Start Guide" + twitter:description: "Learn how to install and use tzst for Python tar.zst archive management in minutes" +--- + # Quick Start Guide This guide will get you up and running with tzst in just a few minutes.