docs: update api references and add sections for authn, authz (#254)

* docs: add shell autocompletion and proton pages in references

* docs: update guides

* chore: fix shield version info

* docs: update api references

* docs: update sidebars styling and add authz,tenant, principal sections

* docs: update managing org page

* docs: add managing roles page

Makefile

@@ -1,8 +1,10 @@
 GOVERSION := $(shell go version | cut -d ' ' -f 3 | cut -d '.' -f 2)
-
+NAME=github.com/odpf/shield
+TAG := "$(shell git rev-list --tags --max-count=1)"
+VERSION := "$(shell git describe --tags ${TAG})"
 .PHONY: build check fmt lint test test-race vet test-cover-html help install proto ui
 .DEFAULT_GOAL := build
-PROTON_COMMIT := "75601b9e0c409299789b6a373f22d9362dfaea69"
+PROTON_COMMIT := "13a222e07cbefed5b480b31f06420e752002877d"
 
 ui:
 	@echo " > generating ui build"
@@ -14,7 +16,7 @@ install:
 	@go get -d github.com/vektra/mockery/v2@v2.13.1
 
 build:
-	CGO_ENABLED=0 go build -o shield .
+	CGO_ENABLED=0 go build -ldflags "-X ${NAME}/cmd.Version=${VERSION}" -o shield .
 
 generate: ## run all go generate in the code base (including generating mock files)
 	go generate ./...
@@ -60,20 +62,19 @@ proto: ## Generate the protobuf files
 	@cp -R proto/odpf/shield/* proto/ && rm -Rf proto/odpf
 	@echo " > protobuf compilation finished"
 
-update-swagger-md:
-	@npx swagger-markdown -i proto/v1beta1/admin.swagger.json -o docs/docs/reference/admin-api.md
-	@npx swagger-markdown -i proto/v1beta1/shield.swagger.json -o docs/docs/reference/api.md
-
 clean-doc:
 	@echo "> cleaning up auto-generated docs"
 	@rm -rf ./docs/docs/reference/cli.md
-	@rm -f ./docs/docs/reference/admin-api.md
-	@rm -f ./docs/docs/reference/api.md
 
-doc: clean-doc update-swagger-md ## Generate api and cli documentation
+doc: clean-doc ## Generate api and cli documentation
 	@echo "> generate cli docs"
 	@go run . reference --plain | sed '1 s,.*,# CLI,' > ./docs/docs/reference/cli.md
+	@echo ">genetaye api docs"
+	@cd $(CURDIR)/docs/docs; yarn docusaurus clean-api-docs all;  yarn docusaurus gen-api-docs all
+
+doc-build: ## Run documentation locally
+	@echo "> building docs"
+	@cd $(CURDIR)/docs/docs; yarn start
 
 help:
 	@grep -E '^[a-zA-Z0-9_-]+:.*?## .*$$' $(MAKEFILE_LIST) | sort | awk 'BEGIN {FS = ":.*?## "}; {printf "\033[36m%-30s\033[0m %s\n", $$1, $$2}'
-

buf.gen.yaml

@@ -15,4 +15,4 @@ plugins:
     opt: "paths=source_relative"
   - plugin: "buf.build/grpc-ecosystem/openapiv2:v2.15.2"
     out: "proto"
-    opt: "allow_merge=false"
+    opt: "allow_merge=true"

docs/README.md

@@ -30,4 +30,18 @@ This command generates static content into the `build` directory and can be serv
 $ GIT_USER=<Your GitHub username> USE_SSH=true yarn deploy
 ```
 
-If you are using GitHub pages for hosting, this command is a convenient way to build the website and push to the `gh-pages` branch.
+If you are using GitHub pages for hosting, this command is a convenient way to build the website and push to the `gh-pages` branch.
+
+### API References
+
+To remove all the auto-generated API reference markdowns:
+
+```
+yarn docusaurus clean-api-docs all
+```
+
+To generate all the API references:
+
+```
+yarn docusaurus gen-api-docs all
+```

docs/docs/admin-portal.md

@@ -0,0 +1,40 @@
+# Admin Portal 
+
+The Admin Portal provides the Shield administrators with a centralized interface for managing the ODPF/Shield platform. This README will guide you through the installation, setup, and usage of the Admin Portal.
+
+### Features 
+*Many of these features are still in development and represents an exhautive list of all the details in our Roadmap for the Admin Portal*
+- Dashboard for an overview of system health and key metrics
+- Tenant (organization) management for multi-tenancy support
+- User authentication and access control 
+- User management with role-based access control
+- Roles and permission management for fine-tuning Shield's behavior
+- Integration with external authentication identity providers/ configure Magic Links/ OTP based sign-ups 
+- Domain Verification for Organizations 
+- Audit Logs for monitoring and much more...
+
+### Starting the Admin Portal
+
+> Make sure you have the Shield server up and running. For details refer [installations](./installation.md) and [configurations](./configurations.md)
+
+Change the current working directory to ui in Shield
+```bash
+$ cd ui
+``` 
+
+Create a **.env** file or export **`SHILD_API_URL`** environment variable for communication with the Shield server. 
+
+```bash title=.env
+# provide the shield server url
+SHILD_API_URL=http://localhost:8000
+```
+Finally to start the Admin portal, run the following commands: 
+
+```bash
+# install all dependencies
+$ npm install
+# start the Admin Portal UI
+$ npm run dev
+```
+
+Open [http://localhost:5173/console](http://localhost:5173/console) with your browser to see the result.