Documentation Generation

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, 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):

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

bazel build //:dist

This will pack everything into a wheel package.

  1. Generate python stubs (.pyi) and documentations (.rst)

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.

  1. Generate HTMLs

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:

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.

Contents