Merge pull request #23 from semiotic-ai/codeblock-warnings

codeblocks and warnings

Author: denverbaumgartner

graphdoc/docs/.nojekyll

@@ -0,0 +1 @@
+ 

graphdoc/docs/conf.py

@@ -20,6 +20,7 @@
     "sphinx.ext.autodoc",
     "sphinx.ext.napoleon",
     "sphinx.ext.viewcode",
+    "sphinx.ext.intersphinx",  # Add intersphinx for better cross-referencing
 ]
 
 # Add Napoleon settings for Google-style docstrings
@@ -53,3 +54,29 @@
 import sys
 
 sys.path.insert(0, os.path.abspath(".."))
+
+# Configure autodoc settings to handle duplicate signatures
+autodoc_default_options = {
+    "members": True,
+    "undoc-members": True,
+    "show-inheritance": True,
+    "member-order": "bysource",
+}
+
+# Configure intersphinx mapping for external projects
+intersphinx_mapping = {
+    "python": ("https://docs.python.org/3", None),
+}
+
+# Ensure that objects are documented only once at their canonical location
+canonical_module_mapping = {}
+
+
+# Configure nitpicky mode to be less strict
+nitpicky = False
+
+
+def setup(app):
+    # Create static directory if it doesn't exist to avoid the warning
+    if not os.path.exists(os.path.join(os.path.dirname(__file__), "_static")):
+        os.makedirs(os.path.join(os.path.dirname(__file__), "_static"))

graphdoc/docs/generate_docs.py

@@ -0,0 +1,102 @@
+#!/usr/bin/env python
+"""
+Script to automatically generate Sphinx documentation RST files.
+Run this script before building the documentation to ensure all RST files are up-to-date.
+"""
+import os
+import shutil
+import subprocess
+import sys
+
+
+def main():
+    # Get the directory where this script is located
+    docs_dir = os.path.dirname(os.path.abspath(__file__))
+
+    # The path to the module we want to document
+    module_dir = os.path.abspath(os.path.join(docs_dir, ".."))
+
+    # Where to output the rst files
+    output_dir = docs_dir
+
+    # Clean up existing RST files except for special ones
+    preserve_files = ["index.rst", "conf.py", "generate_docs.py", "links.rst"]
+    for filename in os.listdir(output_dir):
+        filepath = os.path.join(output_dir, filename)
+        if (
+            filename.endswith(".rst")
+            and filename not in preserve_files
+            and os.path.isfile(filepath)
+        ):
+            print(f"Removing {filepath}")
+            os.unlink(filepath)
+
+    # Run sphinx-apidoc
+    subprocess.run(
+        [
+            "sphinx-apidoc",
+            "-f",  # Force overwriting of existing files
+            "-e",  # Put module documentation before submodule documentation
+            "-M",  # Put module documentation before member documentation
+            "-o",
+            output_dir,  # Output directory
+            module_dir,  # Module directory
+            "setup.py",  # Exclude these files/patterns
+            "*tests*",
+            "*venv*",
+            "*docs*",
+        ]
+    )
+
+    # Add custom content to the module RST files
+    customize_rst_files(output_dir)
+
+    print("\nRST files have been generated successfully!")
+    print("You can now build the documentation with: cd docs && make html")
+
+
+def customize_rst_files(output_dir):
+    """Add custom content to the RST files."""
+    # Example: Add a note about auto-generation to each RST file
+    for filename in os.listdir(output_dir):
+        if filename.endswith(".rst") and filename != "index.rst":
+            filepath = os.path.join(output_dir, filename)
+            with open(filepath, "r") as f:
+                content = f.read()
+
+            # Add noindex to submodules to prevent duplicates
+            content = content.replace(
+                ":show-inheritance:", ":show-inheritance:\n   :noindex:"
+            )
+
+            with open(filepath, "w") as f:
+                f.write(content)
+
+    # Create or update index.rst if it doesn't exist
+    index_path = os.path.join(output_dir, "index.rst")
+    if not os.path.exists(index_path):
+        with open(index_path, "w") as f:
+            f.write(
+                """.. GraphDoc documentation master file
+
+Welcome to GraphDoc's documentation
+==================================
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+   modules
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`
+"""
+            )
+
+
+if __name__ == "__main__":
+    main()

graphdoc/docs/graphdoc.config.rst

@@ -0,0 +1,8 @@
+graphdoc.config module
+======================
+
+.. automodule:: graphdoc.config
+   :members:
+   :undoc-members:
+   :show-inheritance:
+   :noindex:

graphdoc/docs/graphdoc.data.dspy_data.dspy_data_helper.rst

@@ -0,0 +1,8 @@
+graphdoc.data.dspy\_data.dspy\_data\_helper module
+==================================================
+
+.. automodule:: graphdoc.data.dspy_data.dspy_data_helper
+   :members:
+   :undoc-members:
+   :show-inheritance:
+   :noindex:

graphdoc/docs/graphdoc.data.dspy_data.generation_data_helper.rst

@@ -0,0 +1,8 @@
+graphdoc.data.dspy\_data.generation\_data\_helper module
+========================================================
+
+.. automodule:: graphdoc.data.dspy_data.generation_data_helper
+   :members:
+   :undoc-members:
+   :show-inheritance:
+   :noindex:

graphdoc/docs/graphdoc.data.dspy_data.quality_data_helper.rst

@@ -0,0 +1,8 @@
+graphdoc.data.dspy\_data.quality\_data\_helper module
+=====================================================
+
+.. automodule:: graphdoc.data.dspy_data.quality_data_helper
+   :members:
+   :undoc-members:
+   :show-inheritance:
+   :noindex:

graphdoc/docs/graphdoc.data.dspy_data.rst

@@ -1,37 +1,18 @@
 graphdoc.data.dspy\_data package
 ================================
 
-Submodules
-----------
-
-graphdoc.data.dspy\_data.dspy\_data\_helper module
---------------------------------------------------
-
-.. automodule:: graphdoc.data.dspy_data.dspy_data_helper
-   :members:
-   :undoc-members:
-   :show-inheritance:
-
-graphdoc.data.dspy\_data.generation\_data\_helper module
---------------------------------------------------------
-
-.. automodule:: graphdoc.data.dspy_data.generation_data_helper
+.. automodule:: graphdoc.data.dspy_data
    :members:
    :undoc-members:
    :show-inheritance:
+   :noindex:
 
-graphdoc.data.dspy\_data.quality\_data\_helper module
------------------------------------------------------
-
-.. automodule:: graphdoc.data.dspy_data.quality_data_helper
-   :members:
-   :undoc-members:
-   :show-inheritance:
+Submodules
+----------
 
-Module contents
----------------
+.. toctree::
+   :maxdepth: 4
 
-.. automodule:: graphdoc.data.dspy_data
-   :members:
-   :undoc-members:
-   :show-inheritance:
+   graphdoc.data.dspy_data.dspy_data_helper
+   graphdoc.data.dspy_data.generation_data_helper
+   graphdoc.data.dspy_data.quality_data_helper

graphdoc/docs/graphdoc.data.helper.rst

@@ -0,0 +1,8 @@
+graphdoc.data.helper module
+===========================
+
+.. automodule:: graphdoc.data.helper
+   :members:
+   :undoc-members:
+   :show-inheritance:
+   :noindex:

graphdoc/docs/graphdoc.data.local.rst

@@ -0,0 +1,8 @@
+graphdoc.data.local module
+==========================
+
+.. automodule:: graphdoc.data.local
+   :members:
+   :undoc-members:
+   :show-inheritance:
+   :noindex: