WIP Docs

.github/ISSUE_TEMPLATE/sweep-template.yml

@@ -0,0 +1,15 @@
+name: Sweep Issue
+title: 'Sweep: '
+description: For small bugs, features, refactors, and tests to be handled by Sweep, an AI-powered junior developer.
+labels: sweep
+body:
+  - type: textarea
+    id: description
+    attributes:
+      label: Details
+      description: Tell Sweep where and what to edit and provide enough context for a new developer to the codebase
+      placeholder: |
+        Unit Tests: Write unit tests for <FILE>. Test each function in the file. Make sure to test edge cases.
+        Bugs: The bug might be in <FILE>. Here are the logs: ...
+        Features: the new endpoint should use the ... class from <FILE> because it contains ... logic.
+        Refactors: We are migrating this function to ... version because ...

.github/workflows/build_package.yml

@@ -40,5 +40,4 @@ jobs:
       - name: Test import dsp
         shell: bash
         working-directory: ${{ vars.RUNNER_TEMP }}
-        run: python -c "import dsp"
-
+        run: python -c "import dsp"

.gitignore

@@ -7,6 +7,10 @@
 /logs/
 /docs/downloads/
 /docs/experiments/
+/docs/doctrees/
+/docs/html/
+/docs/_build/
+docs/_static/
 
 # Byte-compiled / optimized / DLL files
 __pycache__/

.readthedocs.yaml

@@ -0,0 +1,14 @@
+version: 2
+
+build:
+  os: "ubuntu-22.04"
+  tools:
+    python: "3.9"
+
+python:
+  install:
+    - requirements: docs/requirements.txt
+    - method: pip
+      path: .
+sphinx:
+  configuration: docs/conf.py

Makefile

@@ -0,0 +1,10 @@
+GIT_ROOT ?= $(shell git rev-parse --show-toplevel)
+
+help:	## Show all Makefile targets.
+	@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | awk 'BEGIN {FS = ":.*?## "}; {printf "\033[33m%-30s\033[0m %s\n", $$1, $$2}'
+
+test:	## Run tests via pytest.
+	pytest tests
+
+watch-docs:	## Build and watch documentation.
+	sphinx-autobuild docs/ docs/_build/html --open-browser --watch $(GIT_ROOT)/dspy/

README.md

@@ -1,3 +1,5 @@
+current docs link: https://dspy-ai.readthedocs.io/en/latest/
+
 <p align="center">
   <img align="center" src="docs/images/DSPy8.png" width="460px" />
 </p>
@@ -27,7 +29,7 @@ The **DSPy compiler** _bootstraps_ prompts and finetunes from minimal data **wit
 For complex tasks, **DSPy** can routinely teach powerful models like `GPT-3.5` and local models like `T5-base` or `Llama2-13b` to be much more reliable at tasks. **DSPy** will compile the _same program_ into different few-shot prompts and/or finetunes for each LM.
 
 
-If you want to see **DSPy** in action, **[open our intro tutorial notebook](intro.ipynb)**.
+If you want to see **DSPy** in action, **[open our intro tutorial notebook](docs/getting_started/beginner/intro.ipynb)**.
 
 
 ### Table of Contents

docs/.gitignore

@@ -0,0 +1 @@
+api

docs/DOCS_README.md

@@ -0,0 +1,53 @@
+# Documentation Guide
+
+## A guide for docs contributors
+
+The `docs` directory contains the sphinx source text for DSPy docs, visit
+https://dspy.readthedocs.io/ to read the full documentation.
+
+This guide is made for anyone who's interested in running DSPy documentation locally,
+making changes to it and make contributions. DSPy is made by the thriving community
+behind it, and you're always welcome to make contributions to the project and the
+documentation.
+
+## Build Docs
+
+If you haven't already, clone the DSPy Github repo to a local directory:
+
+```bash
+git clone https://github.com/[DSPY_REPO_PATH].git && cd DSPy
+```
+
+Install all dependencies required for building docs (mainly `sphinx` and its extension):
+
+- [Install poetry](https://python-poetry.org/docs/#installation) - this will help you manage package dependencies
+- `poetry shell` - this command creates a virtual environment, which keeps installed packages contained to this project
+- `poetry install --with docs` - this will install all dependencies needed for building docs
+
+
+#### Watch Docs
+
+Just run the following command from DSPy project's root directory:
+```bash
+make watch-docs
+```
+
+This will start a live-reloading server, which rebuilds the documentation and refreshes any open pages automatically when
+changes are saved. Open your browser to http://0.0.0.0:8000/ to view the generated docs.
+
+#### Build Docs Manually
+
+```bash
+cd docs
+make html
+```
+
+The docs HTML files are now generated under `docs/_build/html` directory, you can preview
+it locally with the following command:
+
+```bash
+python -m http.server 8000 -d _build/html
+```
+
+And open your browser at http://0.0.0.0:8000/ to view the generated docs.
+

docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) -j 8