Merge pull request #1 from srinitha709/update-contributing-docs

Automate examples in documentation (ga4gh#603)

.gitignore

@@ -9,3 +9,4 @@ pyproject.toml
 .idea/
 .DS_Store
 schema/*/build/
+workflows/

CONTRIBUTING.md

@@ -26,7 +26,7 @@ be `250-contributing`.
 
 ## Pull Requests
 [Pull Requests](https://github.com/ga4gh/vrs/pulls) (PRs) for new 
-features should target the `main` branch. For version 
+features should target the `2.x` branch. For version 
 patches, the PR should target the appropriate minor version branch.
 PRs must be approved by at least one project maintainer before they may
 be merged. PR titles must reflect the issue associated with the PR. For

docs/source/conf.py

@@ -52,7 +52,10 @@ def _parse_release_as_version(rls):
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
-    'sphinx.ext.todo'
+    #'sphinx.ext.todo'
+    #'sphinx.ext.autodoc',  # For pulling in docstrings
+    #'sphinx.ext.doctest',  # For testing code examples in documentation
+    #'sphinx.ext.napoleon',  # For Google and NumPy-style docstrings
 ]
 
 # Add any paths that contain templates here, relative to this directory.

docs/source/examples.rst

@@ -0,0 +1,8 @@
+Examples
+========
+
+.. code-block:: python
+
+.. code-block:: python
+
+    >>> multiply(2, 3)

examples/example.py

@@ -0,0 +1,10 @@
+
+def multiply(a, b):
+    """
+    Multiply two numbers together.
+
+    Example:
+        >>> multiply(2, 3)
+        6
+    """
+    return a * b

scripts/update_examples.py

@@ -0,0 +1,45 @@
+import os
+
+def extract_examples(file_path):
+    """Extract examples from source files."""
+    examples = []
+    with open(file_path, 'r') as f:
+        for line in f:
+            if line.strip().startswith(">>>"):
+                examples.append(line.strip())
+    return examples
+
+def update_docs(doc_path, examples):
+    """Insert updated examples into documentation."""
+    print(f"Reading from: {doc_path}")  # Debugging output
+    with open(doc_path, 'r') as f:
+        content = f.readlines()
+
+    updated_content = []
+    inside_placeholder = False
+    for line in content:
+        if line.strip() == "# Examples will be dynamically updated here.":
+            inside_placeholder = True
+            updated_content.append(".. code-block:: python\n\n")
+            for example in examples:
+                updated_content.append(f"    {example}\n")
+        elif inside_placeholder and line.strip() == "":
+            inside_placeholder = False
+        elif not inside_placeholder:
+            updated_content.append(line)
+
+    with open(doc_path, 'w') as f:
+        f.writelines(updated_content)
+    print(f"Updated {doc_path} with new examples.")  # Debugging output
+
+# Example usage
+source_file_path = 'examples/example.py'  # Path to the source code file
+doc_file_path = 'docs/source/examples.rst'  # Path to the documentation file
+
+print(f"Extracting examples from: {source_file_path}")  # Debugging output
+examples = extract_examples(source_file_path)  # Pass the actual file path here
+print(f"Extracted examples: {examples}")  # Debugging output
+
+print(f"Updating documentation: {doc_file_path}")  # Debugging output
+update_docs(doc_file_path, examples)
+print("Documentation updated successfully!")  # Final success message