chore: Add automation to support server doc gen and fix python doc ge…

…n v0 (#2084)

* pass1

* init2

* init3

* init4

* init5

* init6

* init7

* init8

* fix ci

* fix ci

* header change

docs/.gitignore

@@ -7,6 +7,7 @@
 # Generated files
 .docusaurus
 .cache-loader
+.cache
 
 # Misc
 .DS_Store

docs/Makefile

@@ -0,0 +1,13 @@
+generate_service_api_docs:
+	rm -rf ./docs/reference/service-api
+	mkdir -p ./docs/reference/service-api
+	python scripts/generate_service_api_spec.py
+	yarn docusaurus gen-api-docs all
+
+generate_python_sdk_docs:
+	rm -rf ./docs/reference/python-sdk
+	mkdir -p ./docs/reference/python-sdk
+	python scripts/generate_python_sdk_docs.py
+
+generate_reference_docs: generate_service_api_docs generate_python_sdk_docs
+	yarn build

docs/docs/guides/integrations/openai.md

@@ -4,7 +4,7 @@
 
 It’s important to store traces of LLM applications in a central database, both during development and in production. You’ll use these traces for debugging and to help build a dataset of tricky examples to evaluate against while improving your application.
 
-Weave can automatically capture traces for the [openai python library](https://platform.openai.com/docs/api-reference?lang=python). 
+Weave can automatically capture traces for the [openai python library](https://platform.openai.com/docs/reference/python-sdk?lang=python). 
 
 Start capturing by calling `weave.init(<project-name>)` with a project name your choice.
 
@@ -39,7 +39,7 @@ response = client.chat.completions.create(
 
 Wrapping a function with `@weave.op` starts capturing inputs, outputs and app logic so you can debug how data flows through your app. You can deeply nest ops and build a tree of functions that you want to track. This also starts automatically versioning code as you experiment to capture ad-hoc details that haven't been committed to git.
 
-Simply create a function decorated with [`@weave.op`](/guides/tracking/ops) that calls into [openai python library](https://platform.openai.com/docs/api-reference?lang=python).
+Simply create a function decorated with [`@weave.op`](/guides/tracking/ops) that calls into [openai python library](https://platform.openai.com/docs/reference/python-sdk?lang=python).
 
 In the example below, we have 2 functions wrapped with op. This helps us see how intermediate steps, like the retrieval step in a RAG app, are affecting how our app behaves.
 

docs/docs/reference/python-sdk/weave.md

@@ -0,0 +1,139 @@
+---
+hide_table_of_contents: true
+---
+The top-level functions for Weave Trace API.
+---
+
+### <kbd>function</kbd> `init`
+
+```python
+init(
+    project_name: str,
+    settings: Optional[weave.trace.settings.UserSettings, dict[str, Any]] = None
+) → WeaveClient
+```
+
+Initialize weave tracking, logging to a wandb project. 
+
+Logging is initialized globally, so you do not need to keep a reference to the return value of init. 
+
+Following init, calls of weave.op() decorated functions will be logged to the specified project. 
+
+
+
+**Args:**
+
+ - <b>`project_name`</b>:  The name of the Weights & Biases project to log to. 
+
+
+
+**Returns:**
+ A Weave client. 
+
+---
+
+### <kbd>function</kbd> `publish`
+
+```python
+publish(obj: Any, name: Optional[str] = None) → ObjectRef
+```
+
+Save and version a python object. 
+
+If an object with name already exists, and the content hash of obj does not match the latest version of that object, a new version will be created. 
+
+TODO: Need to document how name works with this change. 
+
+
+
+**Args:**
+
+ - <b>`obj`</b>:  The object to save and version. 
+ - <b>`name`</b>:  The name to save the object under. 
+
+
+
+**Returns:**
+ A weave Ref to the saved object. 
+
+---
+
+### <kbd>function</kbd> `ref`
+
+```python
+ref(location: str) → ObjectRef
+```
+
+Construct a Ref to a Weave object. 
+
+TODO: what happens if obj does not exist 
+
+
+
+**Args:**
+
+ - <b>`location`</b>:  A fully-qualified weave ref URI, or if weave.init() has been called, "name:version" or just "name" ("latest" will be used for version in this case). 
+
+
+
+
+
+**Returns:**
+ A weave Ref to the object. 
+
+---
+
+### <kbd>function</kbd> `get_current_call`
+
+```python
+get_current_call() → Optional[ForwardRef('Call')]
+```
+
+Get the Call object for the currently executing Op, within that Op. 
+
+This allows you to access attributes of the Call such as its id or feedback while it is running. 
+
+```python
+@weave.op
+def hello(name: str) -> None:
+     print(f"Hello {name}!")
+     current_call = weave.get_current_call()
+     print(current_call.id)
+``` 
+
+It is also possible to access a Call after the Op has returned. 
+
+If you have the Call's id, perhaps from the UI, you can use the `call` method on the `WeaveClient` returned from `weave.init` to retrieve the Call object. 
+
+```python
+client = weave.init("<project>")
+mycall = client.call("<call_id>")
+``` 
+
+Alternately, after defining your Op you can use its `call` method. For example: 
+
+```python
+@weave.op
+def hello(name: str) -> None:
+     print(f"Hello {name}!")
+
+mycall = hello.call("world")
+print(mycall.id)
+``` 
+
+
+
+**Returns:**
+  The Call object for the currently executing Op, or  None if tracking has not been initialized or this method is  invoked outside an Op. 
+
+---
+
+### <kbd>function</kbd> `finish`
+
+```python
+finish() → None
+```
+
+Stops logging to weave. 
+
+Following finish, calls of weave.op() decorated functions will no longer be logged. You will need to run weave.init() again to resume logging.