pld-generator

Simple utility generator utilizing github's graphql API to request cards from specified project and generate a Project Log Document (PLD) in markdown format.

Usage

Pld Template

In order to generate the PLD, the pld-generator uses a template (default is template.md) and replaces special tags with specific values.

The following tags are supported :

Tag	Description
lucid	Lucid chart diagrams
cards	Github projects cards
table_of_contents	Table of contents with links

In order to be parsed correctly, tags must be surrounded by two pairs of curly braces such as {{cards}}.

Config

By default, the pld-generator searches for a generator_config.toml in the current directory. The config accepts the following options.

Mandatory	Key	Description
✅	github_api_key	Fine grained token
✅	project_number	Github projects number
✅	lucid_client_id	Lucid OAuth client ID
✅	lucid_client_secret	Lucid OAuth client secret
✅	lucid_access_token	Lucid access token generated through OAuth2 process
✅	lucid_refresh_token	Lucid refresh token generated through OAuth2 process
✅	document_id	Lucid document id
	image_width	Specify image width for lucid diagrams
	image_height	Specify image height for lucid diagrams

Here is the expected config format :

[github]
api_key = <github api key>
project_number = <project number on github>

[document-settings] # Optional
image_width = <optional image width for lucid chart>    # Optional
image_height = <optional image height for lucid chart>  # Optional

[lucid] # Optional
lucid_client_id = <lucid OAuth client ID>
lucid_client_secret = <lucid OAuth client secret>
lucid_access_token = <lucid access token generated through OAuth2 process>
lucid_refresh_token = <lucid refresh token generated through OAuth2 process>
document_id = <lucid document id>

Github token

You must provide a fine grained personal access token with the following permissions :

Read access to organization projects
Read access to issues
Read access to metadata

Lucid token

In order to be able to connect to the lucid chart api, you need to get an OAuth2 access token and refresh token. The documentation for getting these tokens is documented however was a bit of a hassle to understand so you may follow the steps here instead. They were especially unclear in a simple user script case such as this one.

Enable developer settings for your lucid chart account
Create an application
Create an OAuth2 client from within the settings of that application
Register the following redirect uri within that app :

https://lucid.app/oauth2/clients/{client id}/redirect

Replace {client id} with your clients id obviously. Stuff like this won't be mentioned later on.

Fill out and open the following authorization url in your browser and grant access

https://lucid.app/oauth2/authorize?client_id={client id}&redirect_uri={previously set redirect uri}&scope=lucidchart.document.content:readonly+lucidchart.document.app.folder+lucidchart.document.app.picker:readonly+offline_access

This url grants the following scope permissions to the access token you will receive :

lucidchart.document.content:readonly
lucidchart.document.app.folder
lucidchart.document.app.picker:readonly
offline_access → Required in order to get refresh token.

Copy the code it shows. We'll refer to it as code from now on.
Request access token and refresh token

curl 'https://api.lucid.co/oauth2/token' \
  --request 'POST' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "code": "",
    "client_id": "",
    "client_secret": "",
    "grant_type": "authorization_code",
    "redirect_uri": ""
  }'

You should now have an access token and a refresh token !

Current state

Still in development

Implemented :

Improvements

Improve storage of gql request → .graphql file ?
Add manual ordering feature
Automatic numbering
Use anyhow for error handling
Restructure serde datamodel module
- ie: model module ?
Github card linter → automatic formatter
Improve deserialization error handling
- For the time being it will the deserialization will fail in a lot of places if the response is of the error type, this should be better managed by checking the status code first

Unhandled edge cases that should have user facing errors

app.rs → if lucid document id is invalid
Lucid module does not handle unauthenticated requests well enough
Ill formatted response in github module get_cards() → needs better error handling

mindoodoo / pld-generator