mirror of https://github.com/CrimsonTome/tldr.git
feat: add documentation for scripts
Signed-off-by: K.B.Dharun Krishna <kbdharunkrishna@gmail.com>pull/23/head
parent
ab46f0494f
commit
b2dc1a28d1
|
@ -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) | ✅ | ❌ | ❌ |
|
|
@ -3,13 +3,31 @@
|
||||||
|
|
||||||
"""
|
"""
|
||||||
A Python script to generate or update alias pages.
|
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':
|
Disclaimer: This script generates a lot of false positives so it
|
||||||
python3 script/set-alias-page.py -p common/vi vim
|
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:
|
Note: If there is a symlink error when using the stage flag remove the `pages.en`
|
||||||
python3 script/set-alias-page.py -S
|
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
|
import argparse
|
||||||
|
|
|
@ -1,6 +1,41 @@
|
||||||
#!/usr/bin/env python3
|
#!/usr/bin/env python3
|
||||||
# SPDX-License-Identifier: MIT
|
# 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 argparse
|
||||||
import os
|
import os
|
||||||
import re
|
import re
|
||||||
|
|
|
@ -1,15 +1,28 @@
|
||||||
#!/bin/sh
|
#!/bin/sh
|
||||||
# SPDX-License-Identifier: MIT
|
# 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
|
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:]')
|
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:]')
|
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
|
if [ "$COMMAND_NAME_FILE" != "$COMMAND_NAME_PAGE" ]; then
|
||||||
echo "$path"
|
echo "Inconsistency found in file: $path: $COMMAND_NAME_PAGE should be $COMMAND_NAME_FILE" >> "$OUTPUT_FILE"
|
||||||
echo "$COMMAND_NAME_FILE"
|
|
||||||
echo "$COMMAND_NAME_PAGE"
|
|
||||||
echo "\n\n"
|
|
||||||
fi
|
fi
|
||||||
done
|
done
|
||||||
|
|
||||||
|
echo "Filename consistency check completed. Output written to: $OUTPUT_FILE"
|
||||||
|
|
Loading…
Reference in New Issue