### Build Documentation with JupyterBook Source: https://context7.com/glims-rgi/rgi_user_guide/llms.txt Executes a bash script to build the RGI user guide website. This process involves cleaning BibTeX references, adding the RGI consortium member list to the introduction, cleaning previous HTML builds, and finally building the JupyterBook documentation. The output is an HTML website located in `docs/_build/html/`. ```bash #!/bin/bash # Execute the build.sh script to generate the full documentation ./build.sh # This script performs the following operations: # 1. Cleans BibTeX references (removes URLs, fixes escape sequences) # 2. Adds the RGI consortium member list to introduction # 3. Cleans previous HTML builds # 4. Builds the JupyterBook documentation # 5. Restores the introduction file to template state # Manual step-by-step execution: python3 clean_refs.py python3 add_consortium.py jupyter-book clean --html docs jupyter-book build docs python3 clean_consortium.py # The output will be in docs/_build/html/ # Expected output: HTML documentation website with index, navigation, and all pages ``` -------------------------------- ### Documentation Structure (Markdown) Source: https://context7.com/glims-rgi/rgi_user_guide/llms.txt Defines the directory structure and main content chapters for the RGI user guide documentation. It outlines the hierarchy from the landing page to references, specifying the purpose of each markdown file. ```markdown # docs/ directory structure ## Main documentation chapters: - welcome.md # Landing page - 01_introduction.md # What is RGI, data policy, citations - 02_regions_definition.md # Geographic region definitions - 03_data_decription.md # File formats, naming conventions, products - 04_revisions.md # Changes from previous versions - 05_description_by_region.md # Region-specific details - 06_dataset_summary.md # Statistical summaries - 07_references.md # Bibliography ``` -------------------------------- ### JupyterBook Configuration (YAML) Source: https://context7.com/glims-rgi/rgi_user_guide/llms.txt Defines the build, styling, and publishing settings for the JupyterBook documentation. This configuration includes metadata, repository details, bibliography settings, HTML output options, Sphinx configurations, notebook execution, and MyST markdown extensions. ```yaml # docs/_config.yml - JupyterBook configuration # Basic book metadata title: The Randolph Glacier Inventory version 7 author: RGI Consortium copyright: "2022" logo: img/rgi_logo/rgi_logo_square.png # GitHub repository integration repository: url: https://github.com/GLIMS-RGI/rgi_user_guide path_to_book: docs branch: main # Bibliography configuration bibtex_bibfiles: - references_cleaned.bib # HTML output settings html: favicon: img/rgi_logo/rgi_logo.svg use_repository_button: true use_issues_button: true use_edit_page_button: true extra_footer: |

This work is licensed under a CC BY 4.0 license.

# Sphinx configuration sphinx: config: html_show_copyright: false bibtex_reference_style: author_year # Notebook execution settings execute: execute_notebooks: auto allow_errors: true # MyST markdown extensions parse: myst_enable_extensions: - dollarmath - linkify - substitution - colon_fence - deflist # Usage: This configuration is automatically read by jupyter-book build docs ``` -------------------------------- ### Check Documentation Links (Bash) Source: https://context7.com/glims-rgi/rgi_user_guide/llms.txt Validates all hyperlinks within the documentation using Jupyter-Book's link checker. It runs a specified script and outputs a report detailing the status of each link, including broken or redirected URLs. ```bash #!/bin/bash # Execute linkcheck.sh to verify all documentation links ./linkcheck.sh # Runs JupyterBook's link checker jupyter-book build docs --builder linkcheck # Output: Report of all HTTP/HTTPS links with status codes # - Valid links (200 OK) # - Broken links (404 Not Found, timeouts, etc.) # - Redirects (301, 302) # Link check results saved to docs/_build/linkcheck/output.txt ``` -------------------------------- ### Clean BibTeX References (Python) Source: https://context7.com/glims-rgi/rgi_user_guide/llms.txt Processes the BibTeX bibliography file to remove unnecessary URL fields and fix formatting issues. It checks for the existence of 'docs/references.bib', cleans specific lines, and saves the output to 'docs/references_cleaned.bib'. ```python # clean_refs.py - Cleans BibTeX references for documentation import os # Only process if bibliography file exists if os.path.exists("docs/references.bib"): with open("docs/references.bib", "r") as input_file: content = input_file.readlines() # Remove URL lines except for specific Norwegian glacier service # Also fix LaTeX escape sequence issues cleaned_content = [] for line in content: # Skip URL lines (except publikasjoner.nve.no references) if "url = {" in line and 'publikasjoner.nve.no' not in line: continue # Fix escaped underscore in specific reference line = line.replace(r'rapport2012{\_}38', 'rapport2012_38') cleaned_content.append(line) # Write cleaned bibliography with open("docs/references_cleaned.bib", "w") as output_file: output_file.writelines(cleaned_content) print("Cleaning complete. The cleaned content has been saved to 'docs/references_clean.bib'.") else: print("No references to clean.") # Output: docs/references_cleaned.bib with cleaned BibTeX entries # This file is referenced in docs/_config.yml for JupyterBook builds ```