diff --git a/docs/.gitignore b/docs/.gitignore index 02478429e4..498b7ba382 100644 --- a/docs/.gitignore +++ b/docs/.gitignore @@ -4,4 +4,10 @@ /.bundle/ /vendor/ /.jekyll-metadata -pagefind* \ No newline at end of file +pagefind* + +# Generated documentation exports +bnd-docs-*.html +bnd-docs-*.pdf +test-output.* +bnd-docs.html \ No newline at end of file diff --git a/docs/EXPORT_README.md b/docs/EXPORT_README.md new file mode 100644 index 0000000000..7624e2dbc7 --- /dev/null +++ b/docs/EXPORT_README.md @@ -0,0 +1,279 @@ +# Exporting Documentation + +This directory contains scripts to export the Bnd documentation to single HTML or PDF files for offline viewing, archiving, or distribution. + +## Overview + +The export functionality provides two main options: +- **Single HTML Export** - Combines all documentation pages into one self-contained HTML file +- **PDF Export** - Creates a PDF document from the documentation + +Both formats are ideal for: +- Offline documentation access +- Archiving documentation snapshots for specific versions +- Distributing documentation without requiring a web server +- Creating searchable documentation archives + +## Quick Start + +### Prerequisites + +1. **Build the documentation first:** + ```bash + ./build.sh + ``` + This generates the static HTML site in the `_site` directory. + +2. **For PDF export, install a PDF generation tool (optional):** + - **wkhtmltopdf** (recommended): `sudo apt-get install wkhtmltopdf` + - **weasyprint**: `pip install weasyprint` + - **Chromium/Chrome**: Available on most systems + - Or use browser's "Print to PDF" feature + +## Usage + +### Export to Single HTML + +Create a single, self-contained HTML file with all documentation: + +```bash +# Export master branch documentation +./export-single-html.sh + +# Export specific version +./export-single-html.sh 7.0.0 + +# Export with custom output filename +./export-single-html.sh master my-docs.html +``` + +**Output:** `bnd-docs-{version}.html` + +Features: +- Complete table of contents with clickable links +- All documentation in a single file +- Print-friendly CSS styles +- Works offline +- Can be opened in any web browser + +### Export to PDF + +Create a PDF file from the documentation: + +```bash +# Export master branch documentation +./export-pdf.sh + +# Export specific version +./export-pdf.sh 7.0.0 + +# Export with custom output filename +./export-pdf.sh master my-docs.pdf +``` + +**Output:** `bnd-docs-{version}.pdf` + +The script will: +1. Auto-detect available PDF generation tools +2. Create a single HTML file (temporary) +3. Convert it to PDF +4. Clean up temporary files + +If no PDF tool is installed, the script will create an HTML file with instructions for manual PDF conversion. + +## Exporting Specific Versions + +### Current Branch/Tag Documentation + +To export documentation for a specific release version from the repository: + +1. **Switch to the release branch or tag:** + ```bash + cd .. # Go to repository root + git checkout 7.0.0 # Or any version tag + cd docs + ``` + +2. **Build the documentation for that version:** + ```bash + ./build.sh + ``` + +3. **Export:** + ```bash + ./export-single-html.sh 7.0.0 + ./export-pdf.sh 7.0.0 + ``` + +### Archived Release Documentation + +For archived releases in the `releases/` folder, use the `export-release.sh` script: + +```bash +# List available releases +ls -1 releases/ + +# Export a specific release to HTML +./export-release.sh 7.0.0 + +# Export a specific release to PDF +./export-release.sh 7.0.0 pdf + +# Export another version +./export-release.sh 6.4.0 html +``` + +This script: +- Works directly with pre-built release documentation in `releases/` folder +- Doesn't require building the documentation +- Supports both HTML and PDF output formats + +## Manual PDF Generation + +If you prefer to create PDFs manually: + +1. Create the HTML file: + ```bash + ./export-single-html.sh + ``` + +2. Open the HTML file in your browser: + ```bash + open bnd-docs-master.html # macOS + xdg-open bnd-docs-master.html # Linux + ``` + +3. Use your browser's Print function: + - Press `Ctrl+P` (or `Cmd+P` on macOS) + - Select "Save as PDF" as the destination + - Adjust page settings if needed + - Save the PDF + +## Advanced Options + +### Installing PDF Tools + +**wkhtmltopdf (recommended):** +```bash +# Ubuntu/Debian +sudo apt-get install wkhtmltopdf + +# macOS +brew install wkhtmltopdf + +# From source +https://wkhtmltopdf.org/downloads.html +``` + +**WeasyPrint:** +```bash +# Using pip +pip install weasyprint + +# Ubuntu/Debian (with dependencies) +sudo apt-get install python3-pip python3-cffi python3-brotli libpango-1.0-0 libpangoft2-1.0-0 +pip install weasyprint +``` + +**Chromium/Chrome:** +```bash +# Ubuntu/Debian +sudo apt-get install chromium-browser + +# macOS +brew install --cask google-chrome +``` + +### Customizing the Export + +The export scripts use Python to process HTML files. You can customize: + +1. **Styling:** Edit the CSS in `export-single-html.sh` (look for the ` + + +
+

Bnd Documentation

+
+ Version: {version}
+ Generated: {generation_date}
+ Source: https://bnd.bndtools.org +
+
+ +
+

Table of Contents

+ +
+ +''' + + # Add all sections + for i, section in enumerate(sections): + section_id = f"section-{i}" + html_output += f'''
+
+

{section["title"]}

+
Source: {section["file"]}
+
+
+{section["content"]} +
+
+ +''' + + html_output += ''' + +''' + + # Write output file + with open(output_file, 'w', encoding='utf-8') as f: + f.write(html_output) + + print(f"✓ Successfully created {output_file}") + print(f" - Total sections: {len(sections)}") + print(f" - File size: {len(html_output) / 1024:.1f} KB") + + return True + +# Run the script +if __name__ == '__main__': + import sys + site_dir = os.environ.get('SITE_DIR', '_site') + output_file = os.environ.get('OUTPUT_FILE', 'bnd-docs.html') + version = os.environ.get('VERSION', 'master') + + success = create_single_html(site_dir, output_file, version) + sys.exit(0 if success else 1) + +PYTHON_SCRIPT + +echo "" +echo "Export complete!" +echo "Output file: ${OUTPUT_FILE}" +echo ""