From b2dc1a28d12e48e8bcffe9ee6999ea54f0565fe8 Mon Sep 17 00:00:00 2001 From: "K.B.Dharun Krishna" Date: Thu, 21 Dec 2023 19:47:18 +0530 Subject: [PATCH] feat: add documentation for scripts Signed-off-by: K.B.Dharun Krishna --- scripts/README.md | 32 ++++++++++++++++++++++++++++++++ scripts/set-alias-page.py | 28 +++++++++++++++++++++++----- scripts/set-more-info-link.py | 35 +++++++++++++++++++++++++++++++++++ scripts/wrong-filename.sh | 23 ++++++++++++++++++----- 4 files changed, 108 insertions(+), 10 deletions(-) create mode 100644 scripts/README.md diff --git a/scripts/README.md b/scripts/README.md new file mode 100644 index 000000000..e13d751d3 --- /dev/null +++ b/scripts/README.md @@ -0,0 +1,32 @@ +# Scripts + +The current directory contains useful scripts used/to use with `tldr` pages. + +## Summary + +This section contains a summary of the scripts available in this directory. For more information about each script, please refer to the +header of each script. + +- [pdf](pdf/README.md) directory contains the `render.py` and `build-pdf.sh` script and related resources to generate a PDF document of tldr-pages for a specific language or platform (or both). +- [build.sh](build.sh) script builds the ZIP archives of the `pages` directory. +- [build-index.sh] script builds the index of available pages. +- [check-pr.sh] script checks the pages syntax and performs various checks on the PR. +- [deploy.sh] script deploys the ZIP and PDF archives to the static website repository. +- [send-to-bot.py] is a Python script that send the build or tests output to tldr-bot. +- [set-alias-pages.py] is a Python script to generate or update alias pages. +- [set-more-info-link.py] is a Python script to generate or update more information links across pages. +- [test.sh] script runs some basic tests on every PR/commit to make sure that the pages are valid and that the code is formatted correctly. +- [wrong-filename.sh] script checks the consistency between the filenames and the page title. + +## Compatibility + +The below table shows the compatibility of user-executable scripts with different platforms. + +| Script | Linux | macOS (`osx`) | Windows | +| ------ | ----- | ----- | ------- | +| [render.py](pdf/render.py) | ✅ | ✅ | ✅ | +| [build-pdf.sh](pdf/build-pdf.sh) | ✅ | ✅ | ❌ | +| [build.sh](build.sh) | ✅ | ✅ | ❌ | +| [set-alias-pages.py](set-alias-pages.py) | ✅ | ✅ | ✅ | +| [set-more-info-link.py](set-more-info-link.py) | ✅ | ✅ | ✅ | +| [wrong-filename.sh](wrong-filename.sh) | ✅ | ❌ | ❌ | diff --git a/scripts/set-alias-page.py b/scripts/set-alias-page.py index 1d420da1d..e1f6a68b9 100755 --- a/scripts/set-alias-page.py +++ b/scripts/set-alias-page.py @@ -3,13 +3,31 @@ """ A Python script to generate or update alias pages. -Call the script with --help to get more information. -For example, add 'vi' as an alias page of 'vim': -python3 script/set-alias-page.py -p common/vi vim +Disclaimer: This script generates a lot of false positives so it +isn't suggested to use the sync option. If used, only stage changes +and commit verified changes for your language. -Read English alias pages and synchronize them into all translations: -python3 script/set-alias-page.py -S +Note: If there is a symlink error when using the stage flag remove the `pages.en` +directory temporarily and try executing it again. + +Usage: + python3 scripts/set-alias-page.py [-p PAGE] [-s] [-S] [COMMAND] + +Options: + -p, --page PAGE + Specify the alias page in the format "platform/alias_command.md". + -s, --stage + Stage modified pages (requires 'git' on $PATH and TLDR_ROOT to be a Git repository). + -S, --sync + Synchronize each translation's alias page (if exists) with that of the English page. + +Examples: + 1. Add 'vi' as an alias page of 'vim': + python3 scripts/set-alias-page.py -p common/vi vim + + 2. Read English alias pages and synchronize them into all translations: + python3 scripts/set-alias-page.py -S """ import argparse diff --git a/scripts/set-more-info-link.py b/scripts/set-more-info-link.py index b0d00fc2f..16f9694ab 100755 --- a/scripts/set-more-info-link.py +++ b/scripts/set-more-info-link.py @@ -1,6 +1,41 @@ #!/usr/bin/env python3 # SPDX-License-Identifier: MIT +""" +This script sets the "More information" link for all translations of a page. +It can be used to add or update the links in translations. + +Note: Before running this script, ensure that TLDR_ROOT is set to the location +of a clone of https://github.com/tldr-pages/tldr, and 'git' is available. +If there is a symlink error when using the stage flag remove the `pages.en` +directory temporarily and try executing it again. + +Usage: python3 scripts/set-more-info-link.py [-p PAGE] [-s] [-S] [LINK] + +Supported Arguments: + -p, --page Specify the page name in the format "platform/command.md". + This option allows setting the link for a specific page. + -s, --stage Stage modified pages for commit. This option requires 'git' + to be on the $PATH and TLDR_ROOT to be a Git repository. + -S, --sync Synchronize each translation's more information link (if + exists) with that of the English page. This is useful to + ensure consistency across translations. + +Positional Argument: + LINK The link to be set as the "More information" link. + +Examples: + 1. Set the link for a specific page: + python3 scripts/set-more-info-link.py -p common/tar.md https://example.com + + 2. Synchronize more information links across translations: + python3 scripts/set-more-info-link.py -S + + 3. Synchronize more information links across translations and stage modified pages for commit: + python3 scripts/set-more-info-link.py -Ss + python3 scripts/set-more-info-link.py --sync --stage +""" + import argparse import os import re diff --git a/scripts/wrong-filename.sh b/scripts/wrong-filename.sh index 008807cbb..108c4e6ad 100755 --- a/scripts/wrong-filename.sh +++ b/scripts/wrong-filename.sh @@ -1,15 +1,28 @@ #!/bin/sh # SPDX-License-Identifier: MIT +# This script checks consistency between the filenames and the page title. +# Usage: ./scripts/wrong-filename.sh + +# Output file for recording inconsistencies +OUTPUT_FILE="filename-consistency-check-output.txt" +# Remove existing output file (if any) +rm -f "$OUTPUT_FILE" + set -e -for path in $(find . -name '*.md' -type f); do +# Iterate through all Markdown files in the 'pages' directories +for path in $(find pages* -name '*.md' -type f); do + # Extract the expected command name from the filename COMMAND_NAME_FILE=$(basename "$path" | head -c-4 | tr '-' ' ' | tr '[:upper:]' '[:lower:]') + + # Extract the command name from the first line of the Markdown file COMMAND_NAME_PAGE=$(head -n1 "$path" | tail -c+3 | tr '-' ' ' | tr '[:upper:]' '[:lower:]') + + # Check if there is a mismatch between filename and content command names if [ "$COMMAND_NAME_FILE" != "$COMMAND_NAME_PAGE" ]; then - echo "$path" - echo "$COMMAND_NAME_FILE" - echo "$COMMAND_NAME_PAGE" - echo "\n\n" + echo "Inconsistency found in file: $path: $COMMAND_NAME_PAGE should be $COMMAND_NAME_FILE" >> "$OUTPUT_FILE" fi done + +echo "Filename consistency check completed. Output written to: $OUTPUT_FILE"