Skip to content

Commit 4d89b1a

Browse files
patrickbirchpatrickbirch
committed
PXB_3453 [DOCS] - add an index 8.4
 new file: docs/index-contents.md new file: generate_index.py modified: mkdocs-base.yml
1 parent 75118a7 commit 4d89b1a

File tree

3 files changed

+268
-6
lines changed

3 files changed

+268
-6
lines changed

‎docs/index-contents.md

+99
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,99 @@
1+
# Index
2+
3+
- [About Percona XtraBackup](about-xtrabackup.md)
4+
- [Accelerate the backup process](accelerate-backup-process.md)
5+
- [Work with AppArmor](work-with-apparmor.md)
6+
- [Apt pinning packages](apt-pinning.md)
7+
- [Backup process overview](backup-overview.md)
8+
- [Work with binary logs](working-with-binary-logs.md)
9+
- [Binary tarball file names available](binary-tarball-names.md)
10+
- [Compile and install from source](compile-xtrabackup.md)
11+
- [Configure xtrabackup](configure-xtrabackup.md)
12+
- [Connection and privileges needed](privileges.md)
13+
- [Copyright and licensing information](copyright-and-licensing-information.md)
14+
- [Create a compressed backup](create-compressed-backup.md)
15+
- [Create a full backup](create-full-backup.md)
16+
- [Create a partial backup](create-partial-backup.md)
17+
- [Create an incremental backup](create-incremental-backup.md)
18+
- [Create an individual partitions backup](create-individual-partition-backup.md)
19+
- [Decompress and prepare a backup](prepare-compressed-backup.md)
20+
- [Dictionary cache](dictionary-cache.md)
21+
- [Encrypt backups](encrypt-backups.md)
22+
- [Encrypted InnoDB tablespace backups](encrypted-innodb-tablespace-backups.md)
23+
- [Exponential backoff](xbcloud-exbackoff.md)
24+
- [FIFO data sink](xbcloud-binary-fifo-datasink.md)
25+
- [Files in packages built for Percona XtraBackup Pro](pro-files.md)
26+
- [Files in the DEB package](apt-files.md)
27+
- [Files in the RPM package built for Percona XtraBackup {{vers}}](yum-files.md)
28+
- [FLUSH TABLES WITH READ LOCK option](flush-tables-with-read-lock.md)
29+
- [Frequently asked questions](faq.md)
30+
- [Get help from Percona](get-help.md)
31+
- [Glossary](glossary.md)
32+
- [How Percona XtraBackup works](how-xtrabackup-works.md)
33+
- [How to create a new (or repair a broken) GTID-based replica](create-gtid-replica.md)
34+
- [How to set up a replica for replication in 6 simple steps with Percona XtraBackup](set-up-replication.md)
35+
- [Improved log statements](log-enhancements.md)
36+
- [Index of files created by Percona XtraBackup](xtrabackup-files.md)
37+
- [Install from a binary tarball](binary-tarball.md)
38+
- [Install overview](installation.md)
39+
- [Install Percona XtraBackup Pro](install-pro.md)
40+
- [Install Percona XtraBackup {{vers}} using downloaded RPM packages](yum-download-rpm.md)
41+
- [Install using downloaded DEB packages](apt-download-deb.md)
42+
- [Install with the Percona-release Tool on Debian-based Systems](apt-repo.md)
43+
- [Limitations](limitations.md)
44+
- [lock-ddl-per-table option improvements](lock-options.md)
45+
- [LRU dump backup](lru-dump-backup.md)
46+
- [Make backups in replication environments](make-backup-in-replication-env.md)
47+
- [Next steps](quickstart-next-steps.md)
48+
- [Percona Toolkit version checking](toolkit-version-check.md)
49+
- [Percona XtraBackup binaries overview](binaries-overview.md)
50+
- [Percona XtraBackup features](features.md)
51+
- [Percona XtraBackup Pro](pxb-pro.md)
52+
- [Percona XtraBackup {{vers}} Documentation](index.md)
53+
- [Permissions needed](permissions.md)
54+
- [Point-in-time recovery](point-in-time-recovery.md)
55+
- [Prepare a full backup](prepare-full-backup.md)
56+
- [Prepare a partial backup](prepare-partial-backup.md)
57+
- [Prepare an incremental backup](prepare-incremental-backup.md)
58+
- [Prepare an individual partitions backup](prepare-individual-partitions-backup.md)
59+
- [Quickstart Overview](quickstart-overview.md)
60+
- [Reduced backup lock time](reduction-in-locks.md)
61+
- [Restore a partial backup](restore-partial-backup.md)
62+
- [Restore full, incremental, compressed backups](restore-a-backup.md)
63+
- [Restore individual tables](restore-individual-tables.md)
64+
- [Restore the backup](quickstart-restore-back.md)
65+
- [Restore the partition from the backup](restore-individual-partitions.md)
66+
- [Run a Docker container](docker.md)
67+
- [Work with SELinux](work-with-selinux.md)
68+
- [Server version and backup version comparison](server-backup-version-comparison.md)
69+
- [Smart memory estimation](smart-memory-estimation.md)
70+
- [Start a Docker container and take a backup](quickstart-docker.md)
71+
- [Store backup history on the server](store-backup-history.md)
72+
- [Take a streaming backup](take-streaming-backup.md)
73+
- [Take an incremental backup using page tracking](page-tracking.md)
74+
- [Throttling backups](throttling-backups.md)
75+
- [Trademark policy](trademark-policy.md)
76+
- [Understand version numbers](xtrabackup-version-numbers.md)
77+
- [Uninstall Percona XtraBackup {{vers}} on Debian and Ubuntu](apt-uninstall-xtrabackup.md)
78+
- [Uninstall Percona XtraBackup {{vers}} on Red Hat Enterprise Linux and CentOS](yum-uninstall-xtrabackup.md)
79+
- [update-curl-utility](update-curl-utility.md)
80+
- [Use a YUM repository to install Percona XtraBackup](yum-repo.md)
81+
- [Use the xbcloud binary with Amazon S3](xbcloud-s3.md)
82+
- [Use the xbcloud binary with an IAM instance profile](xbcloud-iam-profile.md)
83+
- [Use the xbcloud binary with Google Cloud Storage](xbcloud-gcs.md)
84+
- [Use the xbcloud binary with Microsoft Azure Cloud Storage](xbcloud-azure.md)
85+
- [Use the xbcloud binary with MinIO](xbcloud-minio.md)
86+
- [Use the xbcloud binary with Swift](xbcloud-swift.md)
87+
- [Verify backups with replication and pt-checksum](varify-backup.md)
88+
- [The xbcloud binary overview](xbcloud-binary-overview.md)
89+
- [The xbcloud command-line options](xbcloud-options.md)
90+
- [The xbcrypt binary overview](xbcrypt-binary-overview.md)
91+
- [The xbcrypt command-line options](xbcrypt-options.md)
92+
- [The xbstream binary overview](xbstream-binary-overview.md)
93+
- [The xbstream command-line options](xbstream-options.md)
94+
- [The xtrabackup binary overview](xtrabackup-binary-overview.md)
95+
- [The xtrabackup command-line options](xtrabackup-option-reference.md)
96+
- [xtrabackup exit codes](xtrabackup-exit-codes.md)
97+
- [xtrabackup implementation details](xtrabackup-implementation-details.md)
98+
- Release notes/
99+
- [Percona XtraBackup {{vers}} release notes index](release-notes/release-notes.md)

‎generate_index.py

+155
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,155 @@
1+
#!/usr/bin/env python3
2+
3+
"""
4+
generate_index.py - Generate an index of Markdown files in a directory.
5+
6+
Instructions on how to run the script:
7+
8+
python3 generate_index.py
9+
10+
Run this command in the root directory of your project.
11+
12+
This script traverses the 'docs/' directory up to a maximum depth and generates an 'index-contents.md' file listing the Markdown files found. It sorts the files based on the display name, ignoring specified prefixes ('The ', 'Work with ') when sorting. Specified directories are excluded from the index, except that 'release-notes.md' from the 'release-notes' directory is included. The '404.md' file is ignored.
13+
14+
"""
15+
16+
import os
17+
18+
def strip_prefixes(s):
19+
prefixes = ('The ', 'Work with ')
20+
s_lower = s.lower()
21+
for prefix in prefixes:
22+
if s_lower.startswith(prefix.lower()):
23+
return s[len(prefix):]
24+
return s
25+
26+
# Define the directory containing your Markdown files
27+
docs_dir = os.path.join(os.getcwd(), 'docs')
28+
29+
# Path to the index-contents.md file
30+
index_file_path = os.path.join(docs_dir, 'index-contents.md')
31+
32+
# Delete 'index-contents.md' if it exists
33+
if os.path.exists(index_file_path):
34+
os.remove(index_file_path)
35+
print(f"Deleted existing index file: {index_file_path}")
36+
37+
# Prepare the content for index-contents.md
38+
index_content = '# Index\n\n'
39+
40+
# Set the maximum depth (starting from 0)
41+
max_depth = 3
42+
43+
# Directories to exclude from traversal
44+
exclude_dirs = {'_static', 'assets', 'css', 'fonts', 'js', 'Release notes', 'Release notes/8.0'}
45+
46+
# Files to exclude
47+
exclude_files = {'404.md', 'index-contents.md'}
48+
49+
# Calculate the length of the base path to measure depth
50+
base_path_length = len(docs_dir.rstrip(os.sep).split(os.sep))
51+
52+
# Initialize a variable to track the previous directory path
53+
previous_dir = ''
54+
55+
# Walk through the docs directory
56+
for root, dirs, files in os.walk(docs_dir):
57+
# Exclude specified directories from traversal, but keep 'release-notes' to include 'release-notes.md'
58+
dirs[:] = [d for d in dirs if d not in exclude_dirs]
59+
60+
# Calculate the current depth
61+
current_depth = len(root.rstrip(os.sep).split(os.sep)) - base_path_length
62+
63+
# Limit the traversal to the maximum depth
64+
if current_depth >= max_depth:
65+
dirs.clear()
66+
continue
67+
68+
# Sort the directories alphabetically
69+
dirs.sort()
70+
71+
# Exclude non-Markdown files and specified files
72+
files = [f for f in files if f.endswith('.md') and f not in exclude_files]
73+
74+
# Get the relative directory path from docs_dir
75+
relative_dir = os.path.relpath(root, docs_dir)
76+
relative_dir = relative_dir.replace(os.sep, '/')
77+
78+
# Only add directory headings when the directory changes
79+
if relative_dir != previous_dir:
80+
# Add directories as headers except for the root 'docs' directory
81+
if relative_dir != '.':
82+
indent_level = relative_dir.count('/')
83+
indent = ' ' * indent_level
84+
85+
# Modify directory display name
86+
dir_display_name_parts = relative_dir.split('/')
87+
dir_display_name_parts = [
88+
'Release notes' if part.lower() == 'release-notes' else part
89+
for part in dir_display_name_parts
90+
]
91+
dir_display_name = '/'.join(dir_display_name_parts)
92+
93+
# Remove bold formatting from directory names
94+
index_content += f'{indent}- {dir_display_name}/\n'
95+
previous_dir = relative_dir
96+
97+
# Initialize a list to hold file entries with display names
98+
file_entries = []
99+
100+
# Process files to extract display names
101+
for file in files:
102+
# Exclude '404.md' in any location
103+
if file == '404.md':
104+
continue
105+
106+
filepath = os.path.join(root, file)
107+
relative_path = os.path.relpath(filepath, docs_dir)
108+
# Convert backslashes to slashes for cross-platform compatibility
109+
relative_path = relative_path.replace(os.sep, '/')
110+
111+
directories_in_path = os.path.dirname(relative_path).split('/')
112+
113+
if 'release-notes' in directories_in_path:
114+
# Include only 'release-notes.md' from 'release-notes' directory
115+
if file != 'release-notes.md':
116+
continue
117+
else:
118+
# Skip files in excluded directories
119+
if any(ex_dir in directories_in_path for ex_dir in exclude_dirs):
120+
continue
121+
122+
# Extract the display name from the first level 1 heading or filename
123+
display_name = ''
124+
try:
125+
with open(filepath, 'r', encoding='utf-8') as md_file:
126+
for line in md_file:
127+
if line.strip().startswith('# '):
128+
display_name = line.strip()[2:].strip()
129+
break
130+
except Exception as e:
131+
print(f"Error reading file {filepath}: {e}")
132+
continue
133+
134+
if not display_name:
135+
display_name = os.path.splitext(os.path.basename(file))[0]
136+
137+
# For sorting, remove leading prefixes
138+
sort_key = strip_prefixes(display_name).strip().lower()
139+
# Append to the file_entries list
140+
file_entries.append((sort_key, display_name, relative_path))
141+
142+
# Sort the file entries based on the adjusted display name (sort_key)
143+
file_entries.sort()
144+
145+
# Indentation for files within directories
146+
for _, display_name, relative_path in file_entries:
147+
indent_level = relative_path.count('/') - 1
148+
indent = ' ' * indent_level
149+
index_content += f'{indent} - [{display_name}]({relative_path})\n'
150+
151+
# Write the index-contents.md file in the 'docs' directory
152+
with open(index_file_path, 'w', encoding='utf-8') as index_file:
153+
index_file.write(index_content)
154+
155+
print(f"Index generated at {index_file_path}")

‎mkdocs-base.yml

+14-6
Original file line numberDiff line numberDiff line change
@@ -159,12 +159,16 @@ nav:
159159
- features.md
160160
- limitations.md
161161
- how-xtrabackup-works.md
162-
- xtrabackup-version-numbers.md
162+
163163
- Features:
164164
- Backup features:
165165
- lru-dump-backup.md
166166
- throttling-backups.md
167167
- store-backup-history.md
168+
169+
- xbstream features:
170+
- take-streaming-backup.md
171+
- accelerate-backup-process.md
168172
- Prepare features:
169173
- dictionary-cache.md
170174
- Restore features:
@@ -176,6 +180,9 @@ nav:
176180
- log-enhancements.md
177181
- smart-memory-estimation.md
178182
- working-with-binary-logs.md
183+
- xbcloud features:
184+
- xbcloud-binary-fifo-datasink.md
185+
- xbcloud-exbackoff.md
179186
- Binaries:
180187
- Overview: binaries-overview.md
181188
- The xtrabackup binary:
@@ -189,9 +196,7 @@ nav:
189196
- The xbstream binary:
190197
- xbstream-binary-overview.md
191198
- xbstream-options.md
192-
- take-streaming-backup.md
193-
- accelerate-backup-process.md
194-
- encrypt-backups.md
199+
195200
- The xbcloud binary:
196201
- xbcloud-binary-overview.md
197202
- xbcloud-options.md
@@ -202,8 +207,7 @@ nav:
202207
- xbcloud-gcs.md
203208
- xbcloud-azure.md
204209
- xbcloud-minio.md
205-
- xbcloud-binary-fifo-datasink.md
206-
- xbcloud-exbackoff.md
210+
207211
- Install:
208212
- installation.md
209213
- Before you start:
@@ -247,6 +251,8 @@ nav:
247251
- create-compressed-backup.md
248252
- prepare-compressed-backup.md
249253
- encrypted-innodb-tablespace-backups.md
254+
- Take an encrypted backup:
255+
- encrypt-backups.md
250256
- Take a partial backup:
251257
- create-partial-backup.md
252258
- prepare-partial-backup.md
@@ -267,8 +273,10 @@ nav:
267273
- update-curl-utility.md
268274
- Reference:
269275
- xtrabackup-files.md
276+
- xtrabackup-version-numbers.md
270277
- faq.md
271278
- glossary.md
272279
- toolkit-version-check.md
273280
- trademark-policy.md
274281
- copyright-and-licensing-information.md
282+
- Topic Index: index-contents.md

0 commit comments

Comments
 (0)