diff --git a/.github/styles/base/accessibility.yml b/.github/styles/base/accessibility.yml new file mode 100644 index 0000000..07f54ce --- /dev/null +++ b/.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 diff --git a/.github/styles/base/avoid.yml b/.github/styles/base/avoid.yml new file mode 100644 index 0000000..80e2753 --- /dev/null +++ b/.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 \ No newline at end of file diff --git a/.github/workflows/docs-ci.yml b/.github/workflows/docs-ci.yml new file mode 100644 index 0000000..4e15db7 --- /dev/null +++ b/.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 diff --git a/.vale.ini b/.vale.ini new file mode 100644 index 0000000..bfdf5e3 --- /dev/null +++ b/.vale.ini @@ -0,0 +1,5 @@ +StylesPath = .github/styles +MinAlertLevel = suggestion + +[*.rst] +BasedOnStyles = base diff --git a/docs/requirements-docs.txt b/docs/requirements-docs.txt index 135b5a9..aeac77b 100644 --- a/docs/requirements-docs.txt +++ b/docs/requirements-docs.txt @@ -1,4 +1,3 @@ sphinx>=7.3.0 -alabaster==1.0.0 furo==2025.12.19 sphinx-copybutton>=0.5 \ No newline at end of file diff --git a/docs/source/conf.py b/docs/source/conf.py index 7a44b23..0aa8949 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -37,3 +37,6 @@ extensions = [ 'sphinx_copybutton' ] +linkcheck_ignore = [ + r"^https://openai\.com/api/?$", +] \ No newline at end of file diff --git a/docs/source/index.rst b/docs/source/index.rst index 142485d..4b14146 100644 --- a/docs/source/index.rst +++ b/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:: diff --git a/docs/source/installation.rst b/docs/source/installation.rst index 1fd76aa..d5baade 100644 --- a/docs/source/installation.rst +++ b/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 `_ +* An OpenAI API key from `OpenAI `_ * pip * Python 3.10 or later diff --git a/docs/source/smartdoc_workflow.rst b/docs/source/smartdoc_workflow.rst index f63752a..becf37f 100644 --- a/docs/source/smartdoc_workflow.rst +++ b/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 diff --git a/docs/source/using/analyze.rst b/docs/source/using/analyze.rst index 4c0c120..8cff8dd 100644 --- a/docs/source/using/analyze.rst +++ b/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]``: diff --git a/docs/source/using/fail-on.rst b/docs/source/using/fail-on.rst index 1c37d90..697f1e1 100644 --- a/docs/source/using/fail-on.rst +++ b/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 diff --git a/docs/source/using/focus.rst b/docs/source/using/focus.rst index 4522f10..95a10e4 100644 --- a/docs/source/using/focus.rst +++ b/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 -------------