contributing.md

Contributing

Thanks for contributing to this repository.

You can open issues to report problems and discuss new updates to the audit, and open pull requests to contribute to the project.

Contribute to audit documentation

The audit findings are organized and presented with Sphinx-based documentation website, using the PyData Sphinx Theme. The documentation files are written in MyST Markdown.

Notes for authoring markdown

• Ensure every page follows the heading hierarchy: H1, H2, and so on.

• Use the following syntax for embedding images:

  ```{figure} relative_path_to_image.png
      :width: 100%
      :alt: Alt-text for the image
  
      A scatter plot is shown. A plotting tool button is toggled active on the right. The contrast checking score is shown on the bottom left corner (fails).
  ```

• Add meaningful alt-text to images.

• Use the following syntax for embedding videos:

  ```{video} relative_path_to_video.mp4
  :width: 100%
  :playsinline:
  ```

Build documentation locally (optional)

For major updates to the documentation website, it's useful to test your contributions with a local live development of the website. You can build it with the following instructions.

1. Fork and clone the repository:

   git clone https://github.com/<your_username>/bokeh-a11y-audit.git

2. Create a conda environment with the required dependencies and activate it:

   conda env create -f environment-docs.yaml
   conda activate bokeh-a11y-docs

3. Install pre-commit hooks (for linting and formatting):

   pre-commit install

4. Start a live deployment of the documentation website:

   sphinx-autobuild source build/html

   Your local website will be available at localhost:8000. This site is re-built when you save local changes.

Contribute to the dashboard

The audit was performed on a Bokeh dashboard containing some primary components.

Read the dashboard/README for more details about the dashboard source, local execution, and deployment.