Feat/add ci cd

.github/styles/base/accessibility.yml

@@ -0,0 +1,10 @@
+extends: existence
+message: "Avoid vague directional instructions like '%s'. Be specific about the element or section name."
+level: warning
+ignorecase: true
+tokens:
+  - click here
+  - see below
+  - see above
+  - this link
+  - here

.github/styles/base/avoid.yml

@@ -0,0 +1,14 @@
+extends: existence 
+message: "Don't use '%s'."
+ignorecase: true
+level: error
+tokens:
+    - simple
+    - easy
+    - just
+    - simply
+    - obviously
+    - basically
+    - please 
+    - in order to
+    - pretty 

.github/workflows/docs-ci.yml

@@ -0,0 +1,54 @@
+name: docs-ci
+
+on:
+  pull_request:
+    branches: [main]
+
+jobs:
+  run-vale:
+    runs-on: ubuntu-latest
+    steps:
+        - uses: actions/checkout@v4
+
+        - uses: actions/setup-python@v5
+          with:
+            python-version: "3.11"
+
+        - name: Install docs dependencies
+          run: pip install -r docs/requirements-docs.txt
+
+        - uses: errata-ai/vale-action@v2.1.1
+          with:
+            files: docs/source/
+            fail_on_error: true
+
+  build-docs:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install docs dependencies
+        run: pip install -r docs/requirements-docs.txt
+
+      - name: Build Sphinx docs (HTML)
+        run: sphinx-build -b html docs/source docs/build/html
+
+  check-links:
+    needs: build-docs
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install docs dependencies
+        run: pip install -r docs/requirements-docs.txt
+
+      - name: Check links
+        run: sphinx-build -b linkcheck docs/source docs/build/linkcheck

.vale.ini

@@ -0,0 +1,5 @@
+StylesPath = .github/styles
+MinAlertLevel = suggestion
+
+[*.rst]
+BasedOnStyles = base

docs/requirements-docs.txt

@@ -1,4 +1,3 @@
 sphinx>=7.3.0
-alabaster==1.0.0
 furo==2025.12.19
 sphinx-copybutton>=0.5

docs/source/conf.py

@@ -37,3 +37,6 @@
 extensions = [
     'sphinx_copybutton'
 ]
+linkcheck_ignore = [
+    r"^https://openai\.com/api/?$",
+]

docs/source/index.rst

@@ -23,7 +23,7 @@ Features
 * **Powered by OpenAI's GPT-5 model for advanced analysis**: SmartDoc leverages the capabilities of OpenAI's GPT-5-mini model to perform an in-depth analysis of OAS files, providing insights that go beyond basic validation.
 * **OpenAPI-Native (YAML and JSON)**: SmartDoc supports both YAML and JSON formats for OpenAPI Specification files, making it versatile for different development environments.
 * **Automation-Friendly**: Designed to be integrated into CI/CD pipelines, SmartDoc can automatically analyze OAS files during the development process, ensuring continuous quality checks.
-* **Context-Aware Analysis**: SmartDoc evaluates the context of the API definitions, helping to identify issues that may not be apparent through simple schema validation.
+* **Context-Aware Analysis**: SmartDoc evaluates the context of the API definitions, helping to identify issues that may not be apparent through schema validation.
 
 
 .. toctree::

docs/source/installation.rst

@@ -10,7 +10,7 @@ Follow the steps below to install SmartDoc on your system.
 Prerequisites
 -------------
 
-* An OpenAI API key from `OpenAI <https://platform.openai.com/signup>`_
+* An OpenAI API key from `OpenAI <https://openai.com/api/>`_
 * pip 
 * Python 3.10 or later 
 

docs/source/smartdoc_workflow.rst

@@ -10,7 +10,7 @@ It works in three stages:
 2. **Contextual Analysis**: Sends the extracted data to the GPT-5-mini model, which acts as an experienced OAS editor and reviews the specification as a whole or within a user-defined scope.
 3. **Report Generation**: Returns the results in JSON, highlighting issues found and providing recommendations for improvement.
 
-This approach allows SmartDoc to provide context-aware analysis that goes beyond simple schema validation, helping to surface documentation issues earlier in the development process and improving API quality and the developer experience.
+This approach allows SmartDoc to provide context-aware analysis that goes beyond schema validation, helping to surface documentation issues earlier in the development process and improving API quality and the developer experience.
 
 .. admonition:: Remember: LLMs are stateless
     :class: important

docs/source/using/analyze.rst

@@ -1,6 +1,6 @@
-====================
+=====================
 Analyzing an OAS file
-====================
+=====================
 
 The ``analyze`` command allows you to analyze an OpenAPI Specification (OAS) file for quality and completeness. It has one required argument, ``[file]``:
 

docs/source/using/fail-on.rst

@@ -45,7 +45,7 @@ Example output
 Example usage in a CI process (GitHub Actions)
 ----------------------------------------------
 
-Here's a basic GitHub Actions workflow that runs SmartDoc on YAML files when a pull request is opened.
+The following code block a basic GitHub Actions workflow that runs SmartDoc on YAML files when a pull request is opened.
 
 .. code-block:: yaml
     :class: wrap-code

docs/source/using/focus.rst

@@ -15,7 +15,7 @@ The categories for analysis are:
 .. admonition:: Why these categories?
     :class: note
 
-    These are the fundamental building blocks of an API. If these elements are not documented, or are documented incorrectly, developers won't know how to use your API effectively, which can lead to confusion, errors, and wasted time and money. By focusing on these building blocks, SmartDoc ensures the API is usable, predictable, and easy to integrate.
+    These are the fundamental building blocks of an API. If these elements are not documented, or are documented incorrectly, developers won't know how to use your API effectively, which can lead to confusion, errors, and wasted time and money. By focusing on these building blocks, SmartDoc ensures the API is usable and predictable.
 
 Example usage
 -------------