tidocs 1.0.2

A suite of utilities designed to streamline TiDB documentation workflows.

TiDocs: Tools for TiDB Documentation

A toolkit for streamlining TiDB documentation workflows, specializing in document conversion and formatting.

Installation

pip install tidocs

Merge Release Notes (tidocs merge)

This addresses a common challenge in documentation workflows: converting Markdown files containing HTML tables into well-formatted Word and PDF documents. While traditional tools like Pandoc exist, they often struggle with complex HTML tables, resulting in poorly formatted output.

Features

• Merge multiple Markdown files into a single document
• Preserve complex HTML table formatting
• Create automated table of contents
• Convert internal links [Overview](/overview.md) to external links [Overview](https://docs.pingcap.com/tidb/stable/overview).

Usage

The tidocs merge command provides a web interface for combining multiple release notes into a single, well-formatted Word document.

1. Launch the application

   pip install tidocs
   tidocs merge
   

   The application will start and display a URL:

   ✨ Running marimo app Merge Release Notes
   🔗 URL: http://127.0.0.1:8080
   

2. Upload release notes

   To merge release notes from v1.0.0 to v10.0.0, upload all files from release-1.0.0.md to release-10.0.0.md.

3. Configure document information

   These fields will appear on the cover page of the generated Word document.

4. Generate document

   Click Download Word Document to export your formatted Word document. The document will include:

   • Properly formatted tables
   • Complete documentation links
   • Generated Table of Contents

5. Post-process document

   After generating the Word document, follow these steps to finalize it:

   1. Open the downloaded document in Microsoft Word.
   2. Update the table of contents:

   On the References tab, click Update Table > Update entire table > OK

   3. Optional formatting adjustments:
   • Adjust table column widths if needed.
   • Review and adjust page breaks.
   • Check and adjust heading styles.
   4. Export Word document as PDF.

Changelog

v1.0.2

• Fix the issue that Pandoc fails to write docx output to terminal on Windows.

v1.0.1

• Fix the issue that Pandoc becomes non-executable after installation on macOS because Zipfile.extract() doesn't maintain file permissions.

v1.0.0

• Support merging multiple TiDB release notes Markdown files with HTML tables into one well-formatted Word document.