Getting Started

To run this project locally, you will need to install the prerequisites and follow the installation section.

Prerequisites¶

This Project depends on the following projects.

Poetry
```
pip install --user --upgrade poetry
```

Poe the Poet

pip install --user --upgrade poethepoet

Installation¶

Clone the repo

git clone https://github.com/docqai/docq
cd docq

Install Poe the Poet and Poetry

pip install --user --upgrade poethepoet poetry

Install requirements for development
```
poe install-dev
```
Run tests
```
poe test
```

Usage¶

Some useful examples of how this project can be used:

Install requirements¶

poe install-dev

Run tests¶

Unit tests¶

poe test

Integration tests¶

Prepare env vars by supplying a pytest.env file required for the integration tests

cp misc/pytest.env.template pytest.env
## Make edits on pytest.env with the correct values for the test environment then run the tests

poe test-integration

Run the project¶

Prepare env vars by supplying a Streamlit secrets file

cp misc/secrets.toml.template .streamlit/secrets.toml
## Make edits on .streamlit/secrets.toml
## Customise other files in .streamlit/ directory to influence Streamlit behaviour

TIP: Make sure .streamlit directory is in the .gitignore file so it isn't checked in with secrets.
Run the application and it will be available at http://localhost:8501
```
poe run
```
To change the port number
```
poe run --port PORT
```

Run with OpenTelemetry (OTel) Instrumentation¶

This runs the poe run task above with the opentelemetry-instrument command which auto instruments several libraries with tracing and sends traces to the configured exporter. Honeycomb env vars see the /misc/secrets.toml.template

poe run-otel

Run doc site locally¶

poe doc

Generate doc site¶

poe doc-html

Build a docker image for tests¶

poe docker-build --target test --test true

poe docker-run --target test

Build a container image to run the root files only without running any test¶

Build image
```
poe docker-build
```

Set env vars

cp misc/docker.env.template docker.env
## Make edits on docker.env

TIP: Make sure docker.env is in the .gitignore file so it isn't checked in with secrets. It's also safer if you only have the environment variable name for secrets and set the value in your shell with export.

Run container¶

poe docker-run

Release¶

Bump the version number in pyproject.toml (we follow SemVer) Switch to main branch locally and run

./trigger-release.sh

which creates a new release tag which further creates a GitHub release and a container image published to GitHub registry, via GitHub Actions.

For more examples, please refer to the Documentation