docs: fix README inclusion and trailing transition markers

muditbhargava66 · muditbhargava66 · commit ed25db18bdd0 · 2025-02-24T02:49:56.000+05:30
- Exclude README.md from documentation build via conf.py patterns
- Resolve "Document may not end with transition" errors in 19 MD files
- Remove trailing `---` markers from documentation content files
- Add validation checks for Markdown syntax boundaries
- Maintain project root README while hiding from rendered docs
diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md
@@ -32,7 +32,7 @@ Thank you for considering contributing to the SerDes Validation Framework! We we
 
 ## Code of Conduct
 
-Please follow our [Code of Conduct](CODE_OF_CONDUCT.md) when contributing.
+Please follow our [Code of Conduct] when contributing.
 
 ## Reporting Issues
 
@@ -44,6 +44,4 @@ If you encounter any issues or bugs, please open an issue on GitHub and provide
 - Write clear, concise, and meaningful commit messages.
 - Ensure that your code is well-documented with comments and docstrings.
 
-Thank you for your contributions!
-
----
+Thank you for your contributions!
diff --git a/docs/INSTALL.md b/docs/INSTALL.md
@@ -312,6 +312,4 @@ def configure_hardware_testing(
 
 - [Contributing Guide](CONTRIBUTING.md)
 - [Environment Configuration](guides/environment_vars.md)
-- [Troubleshooting Guide](guides/troubleshooting.md)
-
----
+- [Troubleshooting Guide](guides/troubleshooting.md)
diff --git a/docs/README.md b/docs/README.md
@@ -36,6 +36,7 @@ docs/
 │   └── pam4_analysis.md      # PAM4 analysis guide
 ├── guides/                    # User guides
 │   ├── instrument_setup.md   # Hardware setup guide
+│   ├── testing.md   # Testing guide
 │   ├── troubleshooting.md    # Troubleshooting guide
 │   └── environment_vars.md   # Environment config guide
 ├── examples/                  # Code examples
@@ -60,6 +61,4 @@ docs/
 2. Add it to the toctree in index.md
 3. Link it from relevant pages
 4. Build and test locally
-5. Submit a pull request
-
----
+5. Submit a pull request
diff --git a/docs/USAGE.md b/docs/USAGE.md
@@ -461,6 +461,4 @@ def run_hardware_example() -> None:
 
 - [Installation Guide](INSTALL.md)
 - [Contributing Guide](CONTRIBUTING.md)
-- [Mock Testing Tutorial](tutorials/mock_testing.md)
-
----
+- [Mock Testing Tutorial](tutorials/mock_testing.md)
diff --git a/docs/api/eth_224g.md b/docs/api/eth_224g.md
@@ -418,6 +418,4 @@ def validate_measurements(
 
 - [PAM4 Analysis API](pam4_analysis.md)
 - [Mock Controller API](mock_controller.md)
-- [224G Validation Tutorial](../tutorials/224g_validation.md)
-
----
+- [224G Validation Tutorial](../tutorials/224g_validation.md)
diff --git a/docs/api/index.md b/docs/api/index.md
@@ -144,7 +144,7 @@ class MeasurementResults:
 
 ## Module Organization
 
-```plaintext
+```
 serdes_validation_framework/
 ├── instrument_control/
 │   ├── controller.py        # Base controller
@@ -238,16 +238,8 @@ Complete examples are available in the tutorials:
 - [224G Validation](../tutorials/224g_validation.md)
 - [PAM4 Analysis](../tutorials/pam4_analysis.md)
 
-## API Reference
-
-- [Complete Class Reference](classes.md)
-- [Module Reference](modules.md)
-- [Error Reference](errors.md)
-
 ## See Also
 
 - [Installation Guide](../INSTALL.md)
 - [Usage Guide](../USAGE.md)
-- [Contributing Guide](../CONTRIBUTING.md)
-
----
+- [Contributing Guide](../CONTRIBUTING.md)
diff --git a/docs/api/instrument_control.md b/docs/api/instrument_control.md
@@ -434,6 +434,4 @@ def run_test_sequence(
 
 - [Mock Controller Documentation](mock_controller.md)
 - [Testing Guide](../guides/testing.md)
-- [Equipment Setup](../guides/instrument_setup.md)
-
----
+- [Equipment Setup](../guides/instrument_setup.md)
diff --git a/docs/api/mock_controller.md b/docs/api/mock_controller.md
@@ -347,6 +347,4 @@ All tests completed successfully!
 
 - [Instrument Control API](instrument_control.md)
 - [Testing Guide](../guides/testing.md)
-- [Environment Configuration](../guides/environment_vars.md)
-
----
+- [Environment Configuration](../guides/environment_vars.md)
diff --git a/docs/api/pam4_analysis.md b/docs/api/pam4_analysis.md
@@ -434,6 +434,4 @@ def analyze_pam4_signal(
 ## See Also
 
 - [224G Ethernet API](eth_224g.md)
-- [PAM4 Analysis Tutorial](../tutorials/pam4_analysis.md)
-
----
+- [PAM4 Analysis Tutorial](../tutorials/pam4_analysis.md)
diff --git a/docs/conf.py b/docs/conf.py
@@ -36,14 +36,26 @@
     'substitution',         # Substitutions
     'tasklist',            # Task lists
 ]
+myst_heading_anchors = 6  # Enable heading anchors up to 6 levels
+myst_footnote_transition = False  # Disable automatic footnote transitions
+suppress_warnings = [
+    "myst.xref_missing", 
+    "myst.header"
+]
 
 # Templates and themes
 templates_path = ['_templates']
 html_theme = 'sphinx_rtd_theme'
 html_static_path = ['_static']
 
 # Files to exclude
-exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+exclude_patterns = [
+    '_build', 
+    'Thumbs.db', 
+    '.DS_Store',
+    'README.md'
+]
+
 
 # Source file configurations
 source_suffix = {
diff --git a/docs/examples/mock_controller_examples.md b/docs/examples/mock_controller_examples.md
@@ -433,6 +433,4 @@ def mock_instrument(
 
 - [Mock Testing Tutorial](../tutorials/mock_testing.md)
 - [Mock Controller API](../api/mock_controller.md)
-- [Testing Examples](testing_examples.md)
-
----
+- [Testing Examples](testing_examples.md)
diff --git a/docs/examples/testing_examples.md b/docs/examples/testing_examples.md
@@ -432,6 +432,4 @@ if __name__ == '__main__':
 
 - [Mock Controller Examples](mock_controller_examples.md)
 - [Mock Testing Tutorial](../tutorials/mock_testing.md)
-- [Testing Guide](../guides/testing.md)
-
----
+- [Testing Guide](../guides/testing.md)
diff --git a/docs/guides/environment_vars.md b/docs/guides/environment_vars.md
@@ -355,8 +355,6 @@ def configure_environment() -> Dict[str, Any]:
 
 ## See Also
 
-- [Mock Testing Guide](mock_testing.md)
+- [Mock Testing Guide](../tutorials/mock_testing.md)
 - [Instrument Setup Guide](instrument_setup.md)
-- [Troubleshooting Guide](troubleshooting.md)
-
----
+- [Troubleshooting Guide](troubleshooting.md)
diff --git a/docs/guides/instrument_setup.md b/docs/guides/instrument_setup.md
@@ -455,6 +455,4 @@ def verify_mock_responses(
 
 - [Environment Configuration Guide](environment_vars.md)
 - [Troubleshooting Guide](troubleshooting.md)
-- [Mock Testing Tutorial](../tutorials/mock_testing.md)
-
----
+- [Mock Testing Tutorial](../tutorials/mock_testing.md)
diff --git a/docs/guides/testing.md b/docs/guides/testing.md
@@ -0,0 +1 @@
+# Testing
diff --git a/docs/guides/troubleshooting.md b/docs/guides/troubleshooting.md
@@ -476,6 +476,4 @@ def diagnose_analysis_pipeline(
 
 - [Instrument Setup Guide](instrument_setup.md)
 - [Environment Configuration](environment_vars.md)
-- [Mock Testing Tutorial](../tutorials/mock_testing.md)
-
----
+- [Mock Testing Tutorial](../tutorials/mock_testing.md)
diff --git a/docs/index.md b/docs/index.md
@@ -32,7 +32,7 @@ CONTRIBUTING
 
 api/index
 api/mock_controller
-api/instrument_control 
+api/instrument_control
 api/eth_224g
 api/pam4_analysis
 ```
@@ -54,6 +54,7 @@ tutorials/pam4_analysis
 guides/instrument_setup
 guides/troubleshooting
 guides/environment_vars
+guides/testing
 ```
 
 ```{toctree}
diff --git a/docs/tutorials/224g_validation.md b/docs/tutorials/224g_validation.md
@@ -407,6 +407,4 @@ def validate_results(
 
 - IEEE 802.3 224G Ethernet Specification
 - High-Speed Serial Link Design Guide
-- Equipment Manuals and Specifications
-
----
+- Equipment Manuals and Specifications
diff --git a/docs/tutorials/getting_started.md b/docs/tutorials/getting_started.md
@@ -345,6 +345,4 @@ def analyze_pam4_signal() -> None:
 
 - [Mock Controller Documentation](../api/mock_controller.md)
 - [PAM4 Analysis Documentation](../api/pam4_analysis.md)
-- [Environment Configuration](../guides/environment_vars.md)
-
----
+- [Environment Configuration](../guides/environment_vars.md)
diff --git a/docs/tutorials/mock_testing.md b/docs/tutorials/mock_testing.md
@@ -387,6 +387,4 @@ def configure_mock_controller(controller: Any) -> None:
 
 - [Mock Controller API](../api/mock_controller.md)
 - [Instrument Control API](../api/instrument_control.md)
-- [224G Validation Tutorial](224g_validation.md)
-
----
+- [224G Validation Tutorial](224g_validation.md)
diff --git a/docs/tutorials/pam4_analysis.md b/docs/tutorials/pam4_analysis.md
@@ -511,6 +511,7 @@ def validate_measurements(
         
     except Exception as e:
         raise ValueError(f"Measurement validation failed: {e}")
+```
 
 ### 4. Error Handling
 
@@ -733,6 +734,4 @@ def plot_analysis_results(
 
 - PAM4 Modulation Theory
 - Signal Processing Handbook
-- IEEE 802.3 Specifications
-
----
+- IEEE 802.3 Specifications
