Doc cleanup changes. Fixed formatting, fixed headers, make it so the …

…__call__ function is commented in the pdocs.

NOTICE.txt

@@ -23,4 +23,4 @@ This project includes dependencies with the following licenses:
 17. Maturin - Apache 2.0 License OR MIT License
 18. Psutil - BSD 3-Clause "New" or "Revised" License
 19. MkDocs - BSD 2-Clause "Simplified" License
-20. MkDocs Include Markdown Plugin - Apache 2.0 License
+K

README.md

@@ -11,7 +11,6 @@ GenParse is a Python library for constrained generation with language models, sp
 
 First time here? Go to our [Full Documentation](https://genparse.gen.dev/). 
 
-> **💡Tip**: Note that the documentation index is symlinked from the README.md file. If you are on a Windows machine you will need to symlink the README.md file to docs/index.md before building the docs.
 
 ## Installation
 
@@ -65,7 +64,10 @@ This library supports an automated build using [GNU Make](https://www.gnu.org/so
    }
    ```
 
-   Or simply by running `python genparse_tiny_example.py`, which will run on a CPU.
+   Or simply by running:
+   ```bash
+   python genparse_tiny_example.py
+   ```
 
 
 ## Supported language models

docs/contributing.md

@@ -1,9 +1,46 @@
-## Contributing
+## Development
 
+After installation, you can use the following commands for development:
+
+- `make help`: Print available commands
+- `make update`: Update the repository from GitHub
+- `make format`: Format code style using ruff
+- `make docs`: Builds auto-generated API documentation using pdoc
+- `make mkdocs`: Build full documentation using mkdocs
+- `make test`: Run linting (ruff) and tests (pytest with coverage)
+
+## Testing
 Before pushing a new commit, always run:
 
 ```bash
 make test
 ```
 
 This will run all tests and ensure code quality.
+
+## Documentation
+
+To build the auto-generated API documentation, run:
+
+```bash
+make docs
+```
+
+To build the mkdocs documentation, run:
+
+```bash
+make mkdocs
+```
+
+> **💡Tip**: Note that the documentation index is symlinked from the README.md file. If you are on a Windows machine you will need to manually symlink the README.md file to docs/index.md before building the docs.
+
+mkdocs takes documentation in the /docs directory and builds a static html version of it, which it puts into /site. When PRs are approved and merged the docs are rebuilt by a github action and deployed to the [genparse.gen.dev](https://genparse.gen.dev) domain. 
+
+If you want to test the docs on your own branch, run:
+
+```bash
+serve mkdocs
+```
+The results will be served at [localhost:8000](http://localhost:8000).
+
+You can test a deployed version of the docs by pushing to a branch called mkdocs-branch. The github action will automatically deploy the branch to the genparse.dev domain. You can view the results of the action on github and also rerun the action there. 

docs/getting_started.md

@@ -1,12 +1,10 @@
-## Usage Guide
-
 GenParse currently provides a high-level interface for constrained generation via the `InferenceSetup` class. We recommend using this class as its internals may be deprecated without prior warning. 
 
 ```python
 from genparse import InferenceSetup
 ```
 
-### 1. Define your grammar 
+## 1. Define your grammar 
 
 GenParse uses Lark syntax for grammar specification. For example:
 
@@ -25,7 +23,7 @@ For a comprehensive guide on how to write grammars using Lark syntax, please ref
 
 > **💡Tip:** GenParse supports grammars with arbitrary regular expressions. In practice, we recommend avoiding extremely permisive regular expressions (e.g., `/.+/`) since these will lead to significantly slower inference. See [issue #62](https://github.com/probcomp/genparse/issues/62).
 
-### 2. Create an `InferenceSetup` object
+## 2. Create an `InferenceSetup` object
 
 Create an `InferenceSetup` object with your chosen language model and grammar:
 
@@ -34,14 +32,26 @@ setup = InferenceSetup('gpt2', grammar)
 ```
 
 `InferenceSetup` requires the following arguments:
-- **model_name** (str): Name of the language model to use. See the main page for the list of models currently supported by GenParse.
+
+- **model_name** (str): Name of the language model to use. See the README for the list of models currently supported by GenParse.
 - **grammar** (str): The grammar specification in Lark format.
 
-See the docstring for optional arguments that can be provided for more complex usage.
+`InferenceSetup` accepts the following optional arguments:
+- **proposal_name** (str): The type of proposal to use. Options include 'character' and 'token'. Default is 'character'.
+
+- **num_processes** (int): The number of processes to use for parallel proposals. This can help speed up the inference process by utilizing multiple CPU cores. Default: min(mp.cpu_count(), 2)
+- **use_rust_parser** (bool): Whether to use the Rust implementation of the Earley parser for faster inference. If False, the Python implementation is used. Default to True.
+- **use_vllm** (bool or None): Whether to use VLLM for LLM next token probability computations. If None, VLLM is used when possible (i.e., if the vllm library is available and CUDA is enabled). Default is None.
+- **seed** (int or None): A random seed for reproducibility. If provided, it ensures that the inference process is deterministic.
+- **guide_opts** (dict or None): Additional options for the guide, which may include specific configurations for the grammar-based model.
+- **proposal_opts** (dict or None): Additional options for the proposal mechanism, such as parameters specific to the proposal type (e.g., K for token proposal).
+- **llm_opts** (dict or None): Additional options for the language model, such as temperature or top-p settings for sampling.
+- **vllm_engine_opts** (dict or None): Additional options for the VLLM engine, such as data type (dtype). These options are ignored if VLLM is not used.
 
 > **💡Tip:** To try different grammars without having to instantiate new `InferenceSetup` objects each time, use the `update_grammar` method; `setup.update_grammar(new_grammar)` will replace the existing grammar in `setup` with `new_grammar`.
 
-### 3. Run inference
+
+## 3. Run inference
 
 Use the setup object to run SMC inference:
 
@@ -51,33 +61,41 @@ result = setup('Write an SQL query:', n_particles=10, verbosity=1, max_tokens=25
 ```
 
 When calling `InferenceSetup`, the following arguments are required:
-* **prompt** (str): The input prompt to generate samples from.
-* **n_particles** (int): The number of particles (samples) to generate.
+
+- **prompt** (str): The input prompt to generate samples from. This is the starting text for the language model.
+- **n_particles** (int): The number of particles (samples) to generate.
 
 We also highlight the following optional arguments:
-* **max_tokens** (int, optional): The maximum number of tokens to generate. Defaults to 500.
-* **verbosity** (int, optional): Verbosity level. When > 0, particles are printed at each step. Default is 0.
-* **potential** (Callable, optional): A function that when called on a list of particles, returns a list with the log potential values for each particle. Optional. Potentials can be used to guide generation with additional constraints. See below for an overview of potential functions.
-* **ess_threshold** (float, optional): Effective sample size below which resampling is triggered, given as a fraction of **n_particles**. Default is 0.5.
 
+- **method** (str): The sampling method to use. Options include 'smc' for Sequential Monte Carlo and 'is' for importance sampling. Default to 'smc'.
+* **max_tokens** (int): The maximum number of tokens to generate. Defaults to 500.
+
+The following optional arguments are passed in as **kwargs**, which may be expanded over time:
+
+- **potential** (Callable): A function that when called on a list of particles, returns a list with the log potential values for each particle. Potentials can be used to guide generation with additional constraints. See below for an overview of potential functions.
+- **ess_threshold** (float): Effective sample size below which resampling is triggered, given as a fraction of **n_particles**. Default is 0.5.
+* **verbosity** (int): Verbosity level. When > 0, particles are printed at each step. Default is 0.
+- **return_record** (bool): Flag indicating whether to return a record of the inference steps. Default is False.
+- **resample_method** (str): Resampling method to use. Either 'multinomial' or 'stratified'. Default is 'multinomial'.
 
 The result from `InferenceSetup` is a `ParticleApproximation` object. This object contains a collection of particles, each representing a generated text sequence. Each particle has two main attributes:
+
 - `context`: The generated text sequence.
 - `weight`: A numerical value representing the particle's importance weight. The weights are not normalized probabilities. GenParse provides post-processing to convert these weights into meaningful probabilities, which can be accessed via the `.posterior` property:
-   ```python
-   >>> result.posterior
-   {"SELECT name FROM employees GROUP BY name▪" : 1}
-   ```
+```python
+>>> result.posterior
+{"SELECT name FROM employees GROUP BY name▪" : 1}
+```
 
-### 4. Potential functions
+## 4. Potential functions
 
 > **💡 Tip:** Incorporate constraints directly into the grammar when possible, as this will generally improve the quality of inference.
 
 Potential functions can be used to guide generation using additional constraints. A potential function maps (partial) generations to positive real numbers, with higher values indicating a stronger preference for those generations. Intuitively, when applied in SMC, potential functions offer richer signals for resampling steps, allowing computation to be redirected toward more promising particles during the course of generation.
 
 Potentials are provided as input to an `InferenceSetup` call via the `potential` argument and must be defined at the particle beam level. That is, `InferenceSetup` expects potentials to be callables which are provided a *list* of particles as input and return a *list* of log potential values, one for each particle. 
 
-### 5. Visualizing inference
+## 5. Visualizing inference
 
 GenParse additionally provides methods to visualize inference runs. To display the visualization of an inference run:
 

docs/troubleshooting.md

@@ -1,5 +1,3 @@
-## Troubleshooting
-
 If you encounter any issues during installation or setup, please try the following:
 
 1. Check the common issues below.
@@ -11,7 +9,7 @@ If you encounter any issues during installation or setup, please try the followi
 
 If problems persist, please open an issue on our GitHub repository with the error message and your system information.
 
-### Common issues
+## Common issues
 
 - Running `make env` outputs `make: Nothing to be done for 'env'.`
    - Run `make refresh_env` (or `make refresh_env-no-rust`) to force refresh the environment.

genparse/util.py

@@ -260,6 +260,12 @@ def __init__(
         self.batch_model = self._init_step_model()
 
     def _init_step_model(self):
+        """
+        Initialize the step model for batch inference.
+
+        Returns:
+            BatchStepModel: The initialized batch step model.
+        """
         from genparse.batch_inference.steer import BatchStepModel
 
         if self.use_rust_parser:
@@ -316,6 +322,7 @@ def _init_step_model(self):
 
     def __call__(self, prompt, n_particles, method='smc', max_tokens=500, **kwargs):
         """
+        @public
         Run inference with n_particles using the specified method.
 
         Args:
@@ -362,6 +369,11 @@ def update_grammar(self, grammar):
         self.batch_model = self._init_step_model()
 
     def cleanup(self):
+        """
+        Clean up resources used by the batch model.
+
+        This method should be called to release resources when the inference setup is no longer needed.
+        """
         self.batch_model.cleanup()
 
     def free_vllm_gpu_memory(self):

mkdocs.yml

@@ -9,3 +9,4 @@ theme:
   name: material
   palette:
     scheme: slate
+repo_url: https://github.com/probcomp/genparse