Merge pull request jpype-project#1289 from Thrameos/userguide

Userguide update

Author: Thrameos

.azure/doc-requirements.txt

@@ -1,8 +1,8 @@
 # TODO: consider unpinning these?
-Pygments==2.15.0
-docutils==0.14
-commonmark==0.8.1
-recommonmark==0.5.0
+Pygments
+docutils
+commonmark
+recommonmark
 sphinx
 sphinx-rtd-theme
 readthedocs-sphinx-ext

doc/add_labels.py

@@ -0,0 +1,134 @@
+import re
+
+def sanitize_label(text):
+    """
+    Sanitize the label text by removing or replacing special characters.
+    Only allow alphanumeric characters and underscores.
+    """
+    # Replace spaces with underscores
+    text = text.replace(" ", "_")
+    # Remove any characters that are not alphanumeric or underscores
+    text = re.sub(r"[^\w]", "", text)
+    return text.lower()
+
+
+def sync_labels(input_file, output_file):
+    """
+    Synchronize labels with headers in an RST file. Labels are generated based on the chapter, header, subheader, and 
+    sub-subheader structure. The script ensures anchors appear immediately before the correct header text, preserves 
+    all section content, and avoids duplicating labels.
+
+    Header Hierarchy:
+    - Chapters are identified by lines underlined with `*`.
+    - Headers are identified by lines underlined with `=`.
+    - Subheaders are identified by lines underlined with `-`.
+    - Sub-subheaders are identified by lines underlined with `~`.
+
+    Label Format:
+    - Labels follow the format: `.. _chapter_header_subheader_subsubheader:`
+    - Labels are generated dynamically based on the text of the header and its position in the hierarchy.
+    """
+    # Regular expressions to identify underline patterns for different header levels
+    underline_patterns = {
+        "*": "chapter",
+        "=": "header",
+        "-": "subheader",
+        "~": "subsubheader",
+    }
+
+    # Variables to track the current hierarchy of headers
+    current_chapter = None
+    current_header = None
+    current_subheader = None
+
+    # Read the input file
+    with open(input_file, "r") as infile:
+        lines = infile.readlines()
+
+    # Initialize output lines
+    output_lines = []
+    buffer = None  # Holds the previous line to check for headers
+    last_label = None
+    line_count = 0
+
+    for i, line in enumerate(lines):
+        # Debugging: Print the current line being processed
+        print(f"Processing line {i}: {line.strip()}")
+
+        if line.startswith(".."):
+            last_label = line
+            line_count = 0
+
+        # Check if the line is an underline pattern
+        if re.match(r"^\*+$", line):
+            # Process chapter
+            current_chapter = sanitize_label(buffer.strip().lower().replace(" ", "_")) if buffer else None
+            label = f".. _{current_chapter}:\n\n" if current_chapter else None
+            if label and not line_count == 2:
+                print(f"Detected chapter: {current_chapter}, adding label: {label.strip()}")
+                output_lines.append(label)
+            if buffer:
+                print(f"Detected chapter (skip): {current_chapter}, adding label: {label.strip()}")
+                output_lines.append(buffer)  # Add the header text immediately after the label
+            output_lines.append(line)  # Add the underline itself
+            buffer = None
+        elif re.match(r"^=+$", line):
+            # Process header
+            current_header = sanitize_label(buffer.strip().lower().replace(" ", "_")) if buffer else None
+            if not current_header:  # Fallback for empty buffer
+                current_header = "unknown_header"
+            label = f".. _{current_chapter}_{current_header}:\n\n" if current_header else None
+            if label and not line_count == 2:
+                print(f"Detected header: {current_header}, adding label: {label.strip()}")
+                output_lines.append(label)
+            if buffer:
+                print(f"Detected header (skip): {current_chapter}, adding label: {label.strip()}")
+                output_lines.append(buffer)  # Add the header text immediately after the label
+            output_lines.append(line)  # Add the underline itself
+            buffer = None
+        elif re.match(r"^-+$", line):
+            # Process subheader
+            current_subheader = sanitize_label(buffer.strip().lower().replace(" ", "_")) if buffer else None
+            label = f".. _{current_chapter}_{current_subheader}:\n\n" if current_subheader else None
+            if label and not line_count == 2:
+                print(f"Detected subheader: {current_subheader}, adding label: {label.strip()}")
+                output_lines.append(label)
+            if buffer:
+                output_lines.append(buffer)  # Add the header text immediately after the label
+            output_lines.append(line)  # Add the underline itself
+            buffer = None
+        elif re.match(r"^~+$", line):
+            # Process sub-subheader
+            subsubheader_text = sanitize_label(buffer.strip().lower().replace(" ", "_")) if buffer else None
+            label = f".. _{current_chapter}_{subsubheader_text}:\n\n" if subsubheader_text else None
+            if label and not line_count == 2:
+                print(f"Detected sub-subheader: {subsubheader_text}, adding label: {label.strip()}")
+                output_lines.append(label)
+            if buffer:
+                output_lines.append(buffer)  # Add the header text immediately after the label
+            output_lines.append(line)  # Add the underline itself
+            buffer = None
+        else:
+            # If the line isn't an underline, store it in the buffer
+            if buffer:
+                output_lines.append(buffer)  # Add the previous line to the output
+            buffer = line  # Store the current line for processing
+            if not line.isspace():
+                line_count += 1
+
+    if buffer is not None:
+        output_lines.append(buffer)
+
+    # Write the output to the specified file
+    with open(output_file, "w") as outfile:
+        outfile.writelines(output_lines)
+
+    print(f"Labels synchronized successfully! Output written to {output_file}")
+
+
+# Input and output file paths
+input_file = "userguide.rst"
+output_file = "userguide_with_synced_labels.rst"
+
+# Run the label synchronization
+sync_labels(input_file, output_file)

doc/boilerplate.txt

@@ -0,0 +1,51 @@
+Today, we are working on modifying the JPype documentation. The document I 
+have provided is in reStructuredText (RST) format. All responses must adhere 
+to the following guidelines:
+
+1. **Line Length**:
+   - All responses must maintain an 80-character line length limit.
+
+2. **Formatting**:
+   - Match the existing format in terms of anchors, linkage, and overall 
+     structure.
+   - Header levels must follow the established hierarchy:
+     - ****** Chapter Level
+     - ====== Header Level
+     - ------ Subheader Level
+     - ~~~~~~ Subheader Level
+
+3. **Content Style**:
+   - When revisions are presented, they must match the header levels and 
+     formatting of the existing text.
+   - Use descriptive text instead of bullet lists to ensure the document 
+     reads as a cohesive narrative rather than an outline.
+
+4. **Sphinx Compatibility**:
+   - The resulting RST file must conform to Sphinx's interpretation of RST.
+   - Ensure proper use of directives, roles, and syntax supported by Sphinx 
+     to avoid processing errors.
+   - Test the RST file with Sphinx to verify compatibility and correctness 
+     before finalizing revisions.
+
+5. **Avoid Speculative Material**:
+   - Ensure all revisions are based on verified information, authoritative 
+     sources, or established best practices.
+   - Avoid unverified claims, ambiguous statements, or unsupported examples.
+   - Do not include predictions or assumptions about future behavior unless 
+     explicitly supported by authoritative sources or documentation.
+   - Provide sufficient context and explanation for all claims, examples, 
+     and workflows to ensure clarity and reliability.
+
+By following these guidelines, all revisions will align with the existing 
+style and structure of the JPype documentation.
+
+
+
+
+Typical prompts:
+
+Please review the document for consistency of style between the different
+sections. Identify sections that no longer fit the description of a narrative
+(excluding sections in which a narrative would not be expected such as
+glossary)
+

doc/conf.py

@@ -207,15 +207,13 @@ def patch(self, key):
 #html_theme_options = {}
 
 # Add any paths that contain custom themes here, relative to this directory.
-#html_theme_path = []
 
 # on_rtd is whether we are on readthedocs.org, this line of code grabbed from docs.readthedocs.org
 on_rtd = os.environ.get('READTHEDOCS', None) == 'True'
 
 if not on_rtd:  # only import and set the theme if we're building docs locally
     import sphinx_rtd_theme
     html_theme = 'sphinx_rtd_theme'
-    html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
 
 # otherwise, readthedocs.org uses their theme by default, so no need to specify it