{"id":50529176,"url":"https://github.com/gravitee-io/gravitee-doc-gen","last_synced_at":"2026-06-03T11:01:57.540Z","repository":{"id":299426522,"uuid":"966950554","full_name":"gravitee-io/gravitee-doc-gen","owner":"gravitee-io","description":null,"archived":false,"fork":false,"pushed_at":"2026-04-17T10:12:30.000Z","size":329,"stargazers_count":1,"open_issues_count":1,"forks_count":0,"subscribers_count":8,"default_branch":"main","last_synced_at":"2026-04-17T12:18:48.178Z","etag":null,"topics":["security-scan"],"latest_commit_sha":null,"homepage":null,"language":"Go","has_issues":false,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/gravitee-io.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-04-15T17:40:02.000Z","updated_at":"2026-04-17T10:12:33.000Z","dependencies_parsed_at":"2025-06-16T14:43:55.812Z","dependency_job_id":"070a257c-c783-4775-9633-8226c8c70bd7","html_url":"https://github.com/gravitee-io/gravitee-doc-gen","commit_stats":null,"previous_names":["gravitee-io/gravitee-doc-gen"],"tags_count":11,"template":false,"template_full_name":null,"purl":"pkg:github/gravitee-io/gravitee-doc-gen","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gravitee-io%2Fgravitee-doc-gen","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gravitee-io%2Fgravitee-doc-gen/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gravitee-io%2Fgravitee-doc-gen/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gravitee-io%2Fgravitee-doc-gen/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/gravitee-io","download_url":"https://codeload.github.com/gravitee-io/gravitee-doc-gen/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gravitee-io%2Fgravitee-doc-gen/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33860971,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-03T02:00:06.370Z","response_time":59,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["security-scan"],"created_at":"2026-06-03T11:01:56.728Z","updated_at":"2026-06-03T11:01:57.528Z","avatar_url":"https://github.com/gravitee-io.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Gravitee Doc Generation\n\n## Run with Docker on a plugin project\n\nClone the following repository: https://github.com/gravitee-io/gravitee-doc-gen-config somewhere on your local machine.\n\nThen create an env var to point to `src` directory of this repo (ideally add this in your .bashrc/.zshrc file) to ease your pain later.\n\n```shell\nexport DOCGEN_ROOT=\"/path/to/gravitee-doc-gen-config/src\"\n```\n\nThen change the directory to be in your plugin project.\n\nThen run\n```shell\ndocker run --rm -v $DOCGEN_ROOT:/config -v ./:/plugin graviteeio/doc-gen\n````\n\n## Enable doc-gen on a project \n\n```shell\ndocker run --rm -v $DOCGEN_ROOT:/config -v ./:/plugin --entrypoint \"/doc-gen --scaffold plugin --config-dir /config\" graviteeio/doc-gen\n````\n\n\n## Build and run locally (with the example project)\n\nRequirements:\n* go 1.23\n\nBuild the tool\n```shell\nmake build\n```\n\nSet up the config\n```shell\nexport DOCGEN_ROOT=\"$(pwd)/examples/test/config\"\n```\n\nRun it\n```shell\ncd examples/test/plugin\n../../../bin/doc-gen --write\n```\n\nThe docs are already generated in `example/plugin` but you can edit README.md above the generation marker.\n\nYou can `--dryrun` to print the result in the console or `--validate` to validate run the generation without any outputs.\n\n## Overview\n\n## Core\n\nIt has the following features\n\n- Ability to declare more of less required \"chunks\" of documentation\n- Ability to arrange those chunks into one or several output templates\n- Ability to specialise the output template for a type of plugin (e.g policy)  or single plugin\n- Ability to extend this \"core\" with extensions\n- Ability to keep existing custom content in the target file (limited to the top of the file) \n- Usable as a lib or cli\n\nConfiguration consist of two parts\n\n- Files present in the project that must be filled by the writer (dev team, doc team…)\n- Chunks and outputs that are predefined and rule files that must be present in the project\n\nIn the [repo example directory](https://github.com/gravitee-io-labs/readme-gen) you  will find `plugin` and `config` directory. `plugin` is what you user can/should to and `config` is what defines document structures are outputs.\n\nChunks are defined with\n\n- target template to layout the data or to be used as is (e.g a Markdown document)\n    - path are relative to the plugin repository unless they are absolute\n    - most of those file are \n- if it is required\n- data type: point of extension to enable processing data injection in templates\n- data: configuration for the data type, no particular requirements \n\nOutputs are define with :\n\n- Master template in which all chunk will laid out\n- Target file\n- If the target file can keep a part of its existing content  \n\n## Extension (aka data type)\n\n- `table`\n    - ability to define columns\n    - simple data structure that int consumable in a template\n- `options`\n    - can generate a table of all configurable attributes from a json schema (with gravitee extension)\n- `code`\n    - include code in a specific language from one or severals snippets\n    - a file can be included before and after those snippets\n- `raw-examples`\n    - user can define file with plugin custom config exemples\n    - title and description can be added\n    - json or yaml (CRD) are supported\n    - user code is validated against the json schema\n    - code is included into a predefined template specialised by plugin types\n- `gen-examples`\n    - selection of generated example in json or yaml from a schema default values and examples (require to set examples for required value not having defaults)\n- `schema-to-yaml` (alpha)\n    - turns a json schema into documented Yaml configuration file with comments\n        - requires default value or examples for all attributes (not implemented yet)\n- `schema-to-env` (alpha)\n  - turns a json schema into documented ENV vars configuration file with comments\n    - requires default value or examples for all attributes (not implemented yet)\n\n## Other extension\n\nThey are easy to implement, two functions: 1 to validate the `data` part of the chuck and one to handle the generation, they then need to be register in `main.go`\n\n\n### Go template\n\nAs part of this tool some go templates have been added to ease formatting\n\n- `default`\n    - set a value is the one target is not present\n- `ternary`\n    - output something for true or false\n- `indent` \n    - indent code at the right level\n- `pad` \n    - add some padding into code \n- `quote` \n    - add single quote on strings\n- `icz` \n    - increase the given value\n- `joinset`\n    - joins a set (`map[any]bool`) with separator and surround the string values with user input\n- `title` \n    - Upper case the first letter\n- `mvmdheader`\n    -  Include a `.md` file and move their title levels\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgravitee-io%2Fgravitee-doc-gen","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgravitee-io%2Fgravitee-doc-gen","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgravitee-io%2Fgravitee-doc-gen/lists"}