check style (#173)

bc-devrev · web-flow · commit 041ec80b2fa6 · 2025-04-01T08:51:16.000-07:00
* add instructions for local instance

* generate prompt

* refactored for reuse and graceful failure

* send to LLM

* extract revision from element

* specify additional styles

* directory name

* terminology

* refactored

* get diff between original and revision

* terminology violations

* US English

* refactor

* improve diff

* option to skip LLM for testing

* get the title back

* parse response and diff into comments

* parse response and diff into comments

* fix line calculation

* fix line calculation

* post overall comment
diff --git a/.gitignore b/.gitignore
@@ -3,4 +3,5 @@ fern/dist
 fern/*/definition/
 .DS_Store
 .idea
-temp
+temp
+__pycache__
diff --git a/README.md b/README.md
@@ -1,19 +1,17 @@
 # DevRev Docs
 
-Tagging a release on this repository will update the following clients:
+Merging a change in this repository will update the following clients:
 
-- [API Docs](https://devrev.docs.buildwithfern.com)
-
-## What is in this repository?
+- [API Docs](https://developer.devrev.ai)
 
 This repository contains
 
 - DevRev's `Public` OpenAPI spec & `Beta` OpenAPI spec
 - Fern configuration
 
-## What is in the API Definition?
+## API definition
 
-The API Definition contains an OpenAPI specification adapted to be compatible with Fern.
+The API Definition contains an OpenAPI specification adapted to be compatible with Fern. The specs are in `/fern/apis`.
 
 To make sure that the definition is valid, you can use the Fern CLI.
 
@@ -22,9 +20,9 @@ npm install -g fern-api # Installs CLI
 fern check # Checks if the definition is valid
 ```
 
-## What are generators?
+## Generators
 
-Generators read in your API Definition and output artifacts (e.g. the TypeScript SDK Generator) and are tracked in [generators.yml](./fern/api/generators.yml).
+Generators read in your API Definition and output artifacts (the TypeScript SDK Generator) and are tracked in [generators.yml](./fern/api/generators.yml).
 
 To trigger the generators run:
 
@@ -33,15 +31,14 @@ To trigger the generators run:
 fern generate --version <version>
 ```
 
-## Upgrading Fern
-You can use the following command to upgrade fern to the latest version:
-```bash
-fern upgrade --rc
+## Run a local instance
+
+In the root of this repository:
+```
+cd custom-implementation/ && npm i && npm run build && cd ..
+fern docs dev
 ```
 
 ### Troubleshooting
 
 If you run into errors, you can add the ` --log-level debug` flag to get more information.
-
-If you get a 403 error, you may need to first run `fern login`. You might also need to be added
-to the Vellum org in Fern, which requires contacting the fern team in #fern-x-vellum in Slack.
diff --git a/changelog.py b/changelog.py
@@ -1,9 +1,7 @@
 import yaml
 import argparse
-import requests
-import os
 import datetime
-import re
+import llm_client
 
 
 def main(vrn, d):
@@ -17,43 +15,16 @@ def main(vrn, d):
         outfile.write(p)
         print(f"Wrote prompt to {pr_file}.")
 
-    l = gen_log(p)
+    l = llm_client.get_response(p)
 
     log_file = f"./fern/apis/{vrn}/changelog/{d}.md"
-    with open(log_file, 'w', encoding="utf-8") as outfile:
-        outfile.write(l)
-        print(f"Wrote log to {log_file}.")
-
-
-def gen_log(prompt):
-
-    auth = os.environ.get('LLM_JWT')
-    if auth:
-        headers = {"Content-Type": "application/json", "Authorization": f"Bearer {auth}"}
-        payload = {
-            "model": "us.anthropic.claude-3-5-sonnet-20241022-v2:0",
-            "messages": [
-                {
-                    "role": "user",
-                    "content": prompt
-                }
-            ]
-        }
-
-        try:
-            r = requests.post('https://openwebui.dev.devrev-eng.ai/api/chat/completions', json=payload,
-                                headers=headers)
-            log = r.json()['choices'][0]['message']['content']
-            log = re.sub(r"^# .*\n?", '', log, flags=re.MULTILINE)
-            log = re.sub(r"^Here.*\n?", '', log, flags=re.MULTILINE)
-            log = re.sub(r"^Let me know.*\n?", '', log, flags=re.MULTILINE)
-        except Exception as e:
-            print(
-                f"Failed to generate changelog. Error: {type(e)} {e} {r}")
+    if (l):
+        with open(log_file, 'w', encoding="utf-8") as outfile:
+            outfile.write(l)
+            print(f"Wrote log to {log_file}.")
     else:
-        log = "No auth token"
-        
-    return log
+        print(f"Failed to generate {log_file}.")
+
 
 
 def gen_prompt(oasdiff, links, version):
diff --git a/llm_client.py b/llm_client.py
@@ -0,0 +1,40 @@
+import os
+import re
+import requests
+
+def get_response(prompt):
+
+    auth = os.environ.get('LLM_JWT')
+    if auth:
+        headers = {"Content-Type": "application/json", "Authorization": f"Bearer {auth}"}
+        payload = {
+            "model": "us.anthropic.claude-3-5-sonnet-20241022-v2:0",
+            "messages": [
+                {
+                    "role": "user",
+                    "content": prompt
+                }
+            ]
+        }
+
+        try:
+            r = requests.post('https://openwebui.dev.devrev-eng.ai/api/chat/completions', json=payload,
+                                headers=headers)
+            response = r.json()['choices'][0]['message']['content']
+            response = re.sub(r"^# .*\n?", '', response, flags=re.MULTILINE)
+            response = re.sub(r"^Here.*\n?", '', response, flags=re.MULTILINE)
+            response = re.sub(r"^Let me know.*\n?", '', response, flags=re.MULTILINE)
+            return response
+        except Exception as e:
+            print(f"Failed to generate changelog. Error: {type(e)} {e} {r}")
+            return None
+        
+def get_lines_between_tags(text, tag):
+  pattern = r'<' + tag + r'>(.*?)<\/' + tag + r'>'
+  matches = re.findall(pattern, text, re.DOTALL)
+  return "".join([match.strip() for match in matches])
+
+def get_lines_before_tag(text, tag):
+  pattern = r'(.*?)<' + tag + r'>'
+  matches = re.findall(pattern, text, re.DOTALL)
+  return "".join([match.strip() for match in matches])
diff --git a/style/prompt.md b/style/prompt.md
@@ -0,0 +1,3 @@
+You are an expert technical documentation editor. Analyze the included document and revise it so that it adheres to the following style rules. While you can make suggestions for being more concise, be very careful not to remove any facts from the document. Also do not change the document structure, including removing the title or headings, unless the original structure violates any of the guidelines. Also check the terminology given in CSV format inside the `<terminology>` element.
+
+In your response, summarize the violations that you fixed. Return the revised markdown inside a separate element `<document>` element, just like in this request, that contains only the document and no other commentary. I’m going to read your suggestions through an API and need to be able to get just the document for the next stage.
diff --git a/style/sample-common.mdx b/style/sample-common.mdx
@@ -0,0 +1,47 @@
+# DataDog Snap-in
+
+This integration links Datadog's monitoring system with Devrev's incident management, simplifying the process of managing RevOrg incidents triggered by Datadog alerts. It automatically generates new incidents and updates existing incidents in DevRev using data from Datadog, allowing your organisation to address issues efficiently without manual tracking.
+
+### System Features
+
+- Automated Incident Creation: When an incident is triggered in Datadog, the snap-in automatically creates a corresponding incident in DevRev.
+- Automated Incident Updation: When an incident is updated in Datadog, the changes are reflected in DevRev.
+- Real-Time Synchronization: The snap-in ensures that incidents are created or updated in real-time, reducing delays between detection and resolution. DevRev captures the necessary incident details from the Datadog payload, allowing teams to address and mitigate issues.
+- Seamless integration: The snap-in is built to streamline workflows, minimizing the need for manual intervention.
+
+### Installing the Snap-in
+
+1. Open the DevRev marketplace and install the **Datadog** snap-in.
+2. Select the dev org where you want to install the snap-in, confirm your
+selection, and click **Deploy snap-in**.
+3. In DevRev app, setup the connection in **Settings** > **Snap-ins** >
+**Connections** on top.
+    - Search and choose an existing connection or create a new one by clicking
+    **+ Connection**.
+    - Select **Datadog** from the dropdown list.
+    - Give it a connection name and paste your Datadog **API Key**, **Application
+    Key** and **Environment**(prod/dev) in their respective fields.
+
+### Configuration
+
+1. Navigate to **Snap-ins** > **All Snap-ins** > **Datadog** > **Configure**.
+2. Select the connection that you created in the **Connections** tab.
+    
+    This connection is necessary if you wish to bring stage and custom fields to DevRev.
+    
+3. The default owner, part, and default severity value for incidents must be included.
+4. Include the desired stage mapping from Datadog to DevRev.
+5. Click **Save**
+6. Click **Install**.
+7. Copy the webhook URL and follow the below steps to connect it to Datadog via webhook integration.
+    1. Add the following payload in the **Payload** section.
+        - `"aggreg_key": "$AGGREG_KEY"`.
+        - `"alert_metric": "$ALERT_METRIC"`.
+        - `"alert_query": "$ALERT_QUERY"`.
+    2. Click **Install Integration** or **Update Configuration**.
+
+### References
+
+- [DataDog Devrev snap-in marketplace listing](https://marketplace.devrev.ai/datadog-snapin)
+- [DataDog DevRev snapin documentation](https://devrev.ai/docs/integrations/datadog)
+- [DataDog API](https://docs.datadoghq.com/api/latest/)
diff --git a/style/sample-developer.mdx b/style/sample-developer.mdx
@@ -0,0 +1,39 @@
+# Developer sample
+
+## Initialize
+
+Place the following code in the `<body>` section of your HTML page.
+
+```html
+<script>
+  window.plugSDK.init({
+    // Please ensure you replace the app_id with your unique app id
+    app_id: "<your_unique_app_id>",
+  });
+</script>
+```
+```jsx
+<script
+  type="text/javascript"
+  src="https://plug-platform.devrev.ai/static/plug.js"
+></script>;
+```
+```jsx
+useEffect(() => {
+  window.plugSDK.init({
+    // Please ensure you replace the app_id with your unique app id
+    app_id: "<your_unique_app_id>",
+  });
+}, []);
+```
+
+## Tracking user events
+
+To track user events through PLuG, employ the `trackEvent` method provided by the PLuG SDK.
+
+**trackEvent**
+
+```
+window.plugSDK.trackEvent(event_name, properties)
+
+```
diff --git a/style/style-common.md b/style/style-common.md
@@ -0,0 +1,26 @@
+## Rules
+
+For the writing style, apply the following descriptive keywords to analyzing the draft document:
+
+- Writing style: authoritative, comprehensive, helpful
+- Sentence structure: varied, complex, cohesive
+- Vocabulary choice: consistent, technical
+- Grammar and syntax: structured, flawless, articulate
+- Descriptive language: clear, concise, informative
+- Language variant: standard technical/professional US American English; not British, Indian, or other variants.
+
+There are also some very specific style rules that need to be followed:
+
+- Use sentence case (only capitalize the first word and proper nouns) in any type of heading, including in two-level lists.
+- Ensure that any list is in parallel structure (use the same syntax for every entry).
+- Instructions or how-to guides:
+    - They may use two levels; both should be ordered (numbered) lists, not unordered (bulleted).
+    - Instructions should be in imperative mood.
+    - If there is a location or condition in a step, it should be at the front of the sentence, which must still be in imperative.
+    - Steps should be more than a single “click”; combine steps if needed to make them more meaningful.
+- End each list item with a period or other appropriate sentence-ending punctuation, except in the following cases:
+    - If the item consists of a single word, don't add end punctuation.
+    - If the item doesn't include a verb, don't add end punctuation.
+    - If the item is entirely in code font, don't add end punctuation.
+    - If the item is entirely link text or a document title, don't add end punctuation.
+- Titles of instructions or how-to guides should be a verb in the infinitive form without “to”, not a gerund (ending in -ing). Titles of any other type of section should be noun phrases.
diff --git a/style/style-developer.md b/style/style-developer.md
@@ -0,0 +1,18 @@
+## Developer-specific style
+
+- Don't change text inside inline code phrases or code blocks.
+- Always specify a language for codeblocks.
+- Wrap adjacent codeblocks in a `<CodeBlocks>` element.
+- If a codeblock is preceded by a title, move the title to the codeblock.
+  Example before:
+  ```
+  **Request**
+    ```bash
+    curl -X POST -H "Content-Type: application/json"
+    ```
+  Example after:
+  ```
+    ```bash Request
+    curl -X POST -H "Content-Type: application/json"
+    ``` 
+  ```
diff --git a/style/term-common.csv b/style/term-common.csv
@@ -0,0 +1,6 @@
+Deprecated;Approved
+foo;example
+Devrev;DevRev
+RevOrg;workspace
+RevUser;customer
+snapin;snap-in
diff --git a/stylecheck.py b/stylecheck.py

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	+You are an expert technical documentation editor. Analyze the included document and revise it so that it adheres to the following style rules. While you can make suggestions for being more concise, be very careful not to remove any facts from the document. Also do not change the document structure, including removing the title or headings, unless the original structure violates any of the guidelines. Also check the terminology given in CSV format inside the `<terminology>` element.
	`2`	`+`
	`3`	+In your response, summarize the violations that you fixed. Return the revised markdown inside a separate element `<document>` element, just like in this request, that contains only the document and no other commentary. I’m going to read your suggestions through an API and need to be able to get just the document for the next stage.