# Documentation Generation

If you find an error in the PyScreenReader documentation (this site), notice missing or outdated information, or have suggestions to improve clarity or completeness, we warmly welcome your feedback.

There are two ways to contribute:
- **Open an issue** on our GitHub repository describing the problem or suggestion.
- **Submit a pull request** directly if you'd like to propose a fix or improvement.

## Generate Documentation Locally

If you want to directly contribute your changes to *PyScreenReader*, please follow these steps to generate and preview the documentation locally.

*PyScreenReader* uses [Sphinx](https://github.com/sphinx-doc/sphinx), a powerful documentation generator.
Most documentation is written in _GitHub-styled Markdown_, with some files in _reStructuredText_.

The source files for documentation are located in `/doc/source`.

### Install Sphinx

First, ensure your development virtual environment (often named `.venv`) is active. Then, install the development dependencies from the project root
(if you haven't done so):

```shell
pip install -r requirements-dev.txt
```

### Make Changes

Most `.rst` files (API documentations) are auto-generated by `//tools:generate_doc` and they should not be directly modified.
For these files, please modify the documentations at `src/bindings.cpp` instead and then follow the below procedure.  

**If you are modifying `.md` files or `index.rst` files, please directly jump to step `4`.**

Assuming all these operations are performed on the root of the project:
1. Build a wheel package
```shell
bazel build //:dist
```
This will pack everything into a wheel package.  

2. Generate python stubs (.pyi) and documentations (.rst)
```shell
bazel run //tools:generate_doc -- <ABSOLUTE PATH>/bazel-bin/pyscreenreader-<VERSION>-cp312-abi3-<DISTRIBUTION>.whl --stub --doc
```
Make sure the path to the wheel package is valid. This will various depending on your system, project version, and various other factors.  

3. Generate HTMLs
```shell
cd doc
make html
```
If the above command fails, please review the logs to debug any issues.

### Preview
To preview the generated documentation locally, start a Python web server:

```shell
cd build/html
python -m http.server 8000
```

Then open `localhost:8000` in your web browser to view the documentation.

Once you are satisfied with your changes, feel free to open a Pull Request. After your PR is merged, a GitHub workflow running on the `main` branch will publish the updated documentation during next release.