add initial docs

.github/workflows/ci.yml

@@ -32,7 +32,7 @@ jobs:
  arch: x86
  version: 1
  steps:
- - uses: actions/checkout@v2
+ - uses: actions/checkout@v4
  - uses: julia-actions/setup-julia@v1
  with:
  version: ${{ matrix.version }}
@@ -55,9 +55,12 @@ jobs:
  files: lcov.info
  docs:
  name: Documentation
+ permissions:
+ contents: write
+ statuses: write
  runs-on: ubuntu-latest
  steps:
- - uses: actions/checkout@v2
+ - uses: actions/checkout@v4
  - uses: julia-actions/julia-buildpkg@latest
  - uses: julia-actions/julia-docdeploy@latest
  env:

Project.toml

@@ -1,6 +1,6 @@
 name = "OpenPolicyAgent"
 uuid = "8f257efb-743c-4ebc-8197-d291a1f743b4"
-authors = ["Tanmay Mohapatra <tanmaykm@gmail.com>"]
+authors = ["JuliaHub Inc.", "Tanmay Mohapatra <tanmaykm@gmail.com>"]
 version = "0.1.0"
 
 [deps]

README.md

@@ -1,87 +1,10 @@
 # OpenPolicyAgent.jl
 
-# OPA Command Line
+[![Build Status](https://github.com/JuliaComputing/OpenPolicyAgent.jl/workflows/CI/badge.svg)](https://github.com/JuliaComputing/OpenPolicyAgent.jl/actions?query=workflow%3ACI+branch%3Amain)
+[![codecov.io](http://codecov.io/github/JuliaComputing/OpenPolicyAgent.jl/coverage.svg?branch=main)](http://codecov.io/github/JuliaComputing/OpenPolicyAgent.jl?branch=main)
 
-The OPA command line is made available in the `OpenPolicyAgent.CLI` module. To use, import the module. E.g.:
+[Open Policy Agent (OPA)](https://www.openpolicyagent.org/) is an open-source, cloud-native policy engine that allows organizations to declaratively enforce policies across their software stack. It provides a unified, flexible, and efficient way to implement and manage policies for access control, security, and compliance in modern, dynamic environments.
 
-```julia
-julia> using OpenPolicyAgent
+This package provides a Julia interface to the OPA server, and the client APIs to interact with the server. It also includes a command-line interface to the OPA command-line tool.
 
-julia> import OpenPolicyAgent: CLI
-
-julia> ctx = CLI.CommandLine();
-
-julia> CLI.opa(ctx; help=true);
-An open source project to policy-enable your service.
-
-Usage:
- opa [command]
-
-Available Commands:
- bench Benchmark a Rego query
- build Build an OPA bundle
- capabilities Print the capabilities of OPA
- check Check Rego source files
- completion Generate the autocompletion script for the specified shell
- deps Analyze Rego query dependencies
- eval Evaluate a Rego query
- exec Execute against input files
- fmt Format Rego source files
- help Help about any command
- inspect Inspect OPA bundle(s)
- parse Parse Rego source file
- run Start OPA in interactive or server mode
- sign Generate an OPA bundle signature
- test Execute Rego test cases
- version Print the version of OPA
-
-Flags:
- -h, --help help for opa
-
-Use "opa [command] --help" for more information about a command.
-```
-
-# OPA Server
-
-The `OpenPolicyAgent.Server` module includes methods to help start the OPA server,
-monitor it for failures, and restart when required.
-
-```julia
-function start_opa_server(root_path)
- opa_server = OpenPolicyAgent.Server.MonitoredOPAServer(
- joinpath(root_path, "config.yaml"),
- stdout = joinpath(root_path, "server.stdout"),
- stderr = joinpath(root_path, "server.stderr"),
- )
- OpenPolicyAgent.Server.start!(opa_server)
- return opa_server
-end
-
-start_opa_server("/tmp/opaserver")
-```
-
-# OPA Client
-
-OPA exposes domain-agnostic APIs that your service can call to manage and enforce policies. Read this page if you want to integrate an application, service, or tool with OPA. The REST APIs are grouped into the following categories:
-
-- **Policy API** - manage policy loaded into the OPA instance.
-- **Data API** - evaluate rules and retrieve data.
-- **Query API** - execute adhoc queries.
-- **Compile API** - access Rego’s Partial Evaluation functionality.
-- **Health API** - access instance operational health information.
-- **Config API** - view instance configuration.
-- **Status API** - view instance status state.
-
-The `OpenPolicyAgent.Client` module includes methods to help interact with the OPA server using the OpenAPI client.
-
-```julia
-opa_client = OpenPolicyAgent.Client.DataApi(openapi_client)
-
-response, _http_resp = OpenPolicyAgent.Client.get_document(
- opa_client,
- "policies/server/rest/allowed"
-);
-@test response.result == false
-```
-
-OpenAPI [API Documents](src/client/README.md) give more details on the API methods.
+[![](https://img.shields.io/badge/docs-latest-blue.svg)](https://JuliaComputing.github.io/OpenPolicyAgent.jl)

docs/.gitignore

@@ -0,0 +1 @@
+build

docs/Manifest.toml

@@ -0,0 +1,119 @@
+# This file is machine-generated - editing it directly is not advised
+
+julia_version = "1.9.2"
+manifest_format = "2.0"
+project_hash = "e0c77beb18dc1f6cce661ebd60658c0c1a77390f"
+
+[[deps.ANSIColoredPrinters]]
+git-tree-sha1 = "574baf8110975760d391c710b6341da1afa48d8c"
+uuid = "a4c015fc-c6ff-483c-b24f-f7ea428134e9"
+version = "0.0.1"
+
+[[deps.Base64]]
+uuid = "2a0f44e3-6c83-55bd-87e4-b1978d98bd5f"
+
+[[deps.Dates]]
+deps = ["Printf"]
+uuid = "ade2ca70-3891-5945-98fb-dc099432e06a"
+
+[[deps.DocStringExtensions]]
+deps = ["LibGit2"]
+git-tree-sha1 = "2fb1e02f2b635d0845df5d7c167fec4dd739b00d"
+uuid = "ffbed154-4ef7-542d-bbb7-c09d3a79fcae"
+version = "0.9.3"
+
+[[deps.Documenter]]
+deps = ["ANSIColoredPrinters", "Base64", "Dates", "DocStringExtensions", "IOCapture", "InteractiveUtils", "JSON", "LibGit2", "Logging", "Markdown", "REPL", "Test", "Unicode"]
+git-tree-sha1 = "39fd748a73dce4c05a9655475e437170d8fb1b67"
+uuid = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
+version = "0.27.25"
+
+[[deps.IOCapture]]
+deps = ["Logging", "Random"]
+git-tree-sha1 = "d75853a0bdbfb1ac815478bacd89cd27b550ace6"
+uuid = "b5f81e59-6552-4d32-b1f0-c071b021bf89"
+version = "0.2.3"
+
+[[deps.InteractiveUtils]]
+deps = ["Markdown"]
+uuid = "b77e0a4c-d291-57a0-90e8-8db25a27a240"
+
+[[deps.JSON]]
+deps = ["Dates", "Mmap", "Parsers", "Unicode"]
+git-tree-sha1 = "31e996f0a15c7b280ba9f76636b3ff9e2ae58c9a"
+uuid = "682c06a0-de6a-54ab-a142-c8b1cf79cde6"
+version = "0.21.4"
+
+[[deps.LibGit2]]
+deps = ["Base64", "NetworkOptions", "Printf", "SHA"]
+uuid = "76f85450-5226-5b5a-8eaa-529ad045b433"
+
+[[deps.Logging]]
+uuid = "56ddb016-857b-54e1-b83d-db4d58db5568"
+
+[[deps.Markdown]]
+deps = ["Base64"]
+uuid = "d6f4376e-aef5-505a-96c1-9c027394607a"
+
+[[deps.Mmap]]
+uuid = "a63ad114-7e13-5084-954f-fe012c677804"
+
+[[deps.NetworkOptions]]
+uuid = "ca575930-c2e3-43a9-ace4-1e988b2c1908"
+version = "1.2.0"
+
+[[deps.Parsers]]
+deps = ["Dates", "PrecompileTools", "UUIDs"]
+git-tree-sha1 = "716e24b21538abc91f6205fd1d8363f39b442851"
+uuid = "69de0a69-1ddd-5017-9359-2bf0b02dc9f0"
+version = "2.7.2"
+
+[[deps.PrecompileTools]]
+deps = ["Preferences"]
+git-tree-sha1 = "9673d39decc5feece56ef3940e5dafba15ba0f81"
+uuid = "aea7be01-6a6a-4083-8856-8a6e6704d82a"
+version = "1.1.2"
+
+[[deps.Preferences]]
+deps = ["TOML"]
+git-tree-sha1 = "7eb1686b4f04b82f96ed7a4ea5890a4f0c7a09f1"
+uuid = "21216c6a-2e73-6563-6e65-726566657250"
+version = "1.4.0"
+
+[[deps.Printf]]
+deps = ["Unicode"]
+uuid = "de0858da-6303-5e67-8744-51eddeeeb8d7"
+
+[[deps.REPL]]
+deps = ["InteractiveUtils", "Markdown", "Sockets", "Unicode"]
+uuid = "3fa0cd96-eef1-5676-8a61-b3b8758bbffb"
+
+[[deps.Random]]
+deps = ["SHA", "Serialization"]
+uuid = "9a3f8284-a2c9-5f02-9a11-845980a1fd5c"
+
+[[deps.SHA]]
+uuid = "ea8e919c-243c-51af-8825-aaa63cd721ce"
+version = "0.7.0"
+
+[[deps.Serialization]]
+uuid = "9e88b42a-f829-5b0c-bbe9-9e923198166b"
+
+[[deps.Sockets]]
+uuid = "6462fe0b-24de-5631-8697-dd941f90decc"
+
+[[deps.TOML]]
+deps = ["Dates"]
+uuid = "fa267f1f-6049-4f14-aa54-33bafae1ed76"
+version = "1.0.3"
+
+[[deps.Test]]
+deps = ["InteractiveUtils", "Logging", "Random", "Serialization"]
+uuid = "8dfed614-e22c-5e08-85e1-65c5234f0b40"
+
+[[deps.UUIDs]]
+deps = ["Random", "SHA"]
+uuid = "cf7118a7-6976-5b1a-9a39-7adc72f591a4"
+
+[[deps.Unicode]]
+uuid = "4ec0a83e-493e-50e2-b9ac-8f72acf5a8f5"

docs/Project.toml

@@ -0,0 +1,5 @@
+[deps]
+Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
+
+[compat]
+Documenter = "0.27"

docs/make.jl

@@ -0,0 +1,23 @@
+import Pkg
+Pkg.add("Documenter")
+
+using Documenter
+using OpenPolicyAgent
+
+makedocs(
+ sitename = "OpenPolicyAgent.jl",
+ format = Documenter.HTML(
+ prettyurls = get(ENV, "CI", nothing) == "true"
+ ),
+ pages = [
+ "Home" => "index.md",
+ "Client" => "client.md",
+ "Server" => "server.md",
+ "Command Line" => "commandline.md",
+ ],
+)
+
+deploydocs(
+ repo = "github.com/JuliaComputing/OpenPolicyAgent.jl.git",
+ push_preview = true,
+)

docs/src/client.md

@@ -0,0 +1,25 @@
+# OPA Client
+
+OPA exposes domain-agnostic APIs that your service can call to manage and enforce policies. Read this page if you want to integrate an application, service, or tool with OPA. The REST APIs are grouped into the following categories:
+
+- **Policy API** - manage policy loaded into the OPA instance.
+- **Data API** - evaluate rules and retrieve data.
+- **Query API** - execute adhoc queries.
+- **Compile API** - access Rego’s Partial Evaluation functionality.
+- **Health API** - access instance operational health information.
+- **Config API** - view instance configuration.
+- **Status API** - view instance status state.
+
+The `OpenPolicyAgent.Client` module includes methods to help interact with the OPA server using the OpenAPI client.
+
+```julia
+opa_client = OpenPolicyAgent.Client.DataApi(openapi_client)
+
+response, _http_resp = OpenPolicyAgent.Client.get_document(
+ opa_client,
+ "policies/server/rest/allowed"
+);
+@test response.result == false
+```
+
+OpenAPI [API Documents](https://github.com/JuliaComputing/OpenPolicyAgent.jl/blob/main/src/client/README.md) give more details on the API methods.

docs/src/commandline.md

@@ -0,0 +1,42 @@
+# OPA Command Line
+
+The OPA (Open Policy Agent) command-line tool is a versatile utility that empowers users to interact with and manage OPA policies and data. It allows users to perform various tasks, such as evaluating policies, testing Rego expressions, and querying data, all from the command line. This tool is invaluable for policy development, debugging, and troubleshooting, providing an accessible way to work with OPA without the need for complex integration. It's an essential companion for developers and administrators working with OPA, simplifying the process of authoring, testing, and refining policies to ensure robust and consistent policy enforcement across software systems.
+
+The OPA command line is made available in the `OpenPolicyAgent.CLI` module. To use, import the module. E.g.:
+
+```julia
+julia> using OpenPolicyAgent
+
+julia> import OpenPolicyAgent: CLI
+
+julia> ctx = CLI.CommandLine();
+
+julia> CLI.opa(ctx; help=true);
+An open source project to policy-enable your service.
+
+Usage:
+ opa [command]
+
+Available Commands:
+ bench Benchmark a Rego query
+ build Build an OPA bundle
+ capabilities Print the capabilities of OPA
+ check Check Rego source files
+ completion Generate the autocompletion script for the specified shell
+ deps Analyze Rego query dependencies
+ eval Evaluate a Rego query
+ exec Execute against input files
+ fmt Format Rego source files
+ help Help about any command
+ inspect Inspect OPA bundle(s)
+ parse Parse Rego source file
+ run Start OPA in interactive or server mode
+ sign Generate an OPA bundle signature
+ test Execute Rego test cases
+ version Print the version of OPA
+
+Flags:
+ -h, --help help for opa
+
+Use "opa [command] --help" for more information about a command.
+```

docs/src/index.md

@@ -0,0 +1,7 @@
+# OpenPolicyAgent.jl
+
+[Open Policy Agent (OPA)](https://www.openpolicyagent.org/) is an open-source, cloud-native policy engine that allows organizations to declaratively enforce policies across their software stack. It provides a unified, flexible, and efficient way to implement and manage policies for access control, security, and compliance in modern, dynamic environments. OPA excels at decoupling policy decision logic from application code, enabling fine-grained control over authorization, resource validation, and more.
+
+Its expressive policy language, called [Rego](https://www.openpolicyagent.org/docs/latest/#rego), allows users to define complex policies in a human-readable format. OPA is widely adopted in cloud-native ecosystems, helping organizations ensure consistent policy enforcement across services, APIs, and infrastructure components, making it a crucial tool for enhancing security and governance in modern software systems.
+
+This package provides a Julia interface to the OPA server, and the client APIs to interact with the server. It also includes a command-line interface to the OPA command-line tool.

docs/src/server.md

@@ -0,0 +1,20 @@
+# OPA Server
+
+The OPA (Open Policy Agent) server is a critical component of the OPA ecosystem, serving as a central policy decision point. It's a standalone service that evaluates policies written in the Rego language and makes access control decisions based on those policies. The OPA server allows for efficient policy enforcement across various parts of a software stack, including microservices, APIs, and cloud infrastructure. It receives policy queries, typically in the form of JSON or structured data, and returns decisions, enabling fine-grained control over authorization and compliance. With its ability to scale and distribute policy evaluations, the OPA server plays a crucial role in ensuring consistent and dynamic policy enforcement in complex, modern, and cloud-native environments, enhancing security and governance across the entire system.
+
+The `OpenPolicyAgent.Server` module includes methods to help start the OPA server,
+monitor it for failures, and restart when required.
+
+```julia
+function start_opa_server(root_path)
+ opa_server = OpenPolicyAgent.Server.MonitoredOPAServer(
+ joinpath(root_path, "config.yaml"),
+ stdout = joinpath(root_path, "server.stdout"),
+ stderr = joinpath(root_path, "server.stderr"),
+ )
+ OpenPolicyAgent.Server.start!(opa_server)
+ return opa_server
+end
+
+start_opa_server("/tmp/opaserver")
+```