{"id":19879601,"url":"https://github.com/mathisloge/protocol-doc-generation","last_synced_at":"2025-04-12T21:58:10.690Z","repository":{"id":47627906,"uuid":"376269681","full_name":"mathisloge/protocol-doc-generation","owner":"mathisloge","description":"Generates protocol descriptions from CommsDSL-Specification schema definition files.","archived":false,"fork":false,"pushed_at":"2022-04-28T15:02:25.000Z","size":342,"stargazers_count":3,"open_issues_count":1,"forks_count":1,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-04-12T21:58:06.859Z","etag":null,"topics":["code-generation","tools"],"latest_commit_sha":null,"homepage":"","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mathisloge.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2021-06-12T11:08:15.000Z","updated_at":"2021-11-10T13:44:08.000Z","dependencies_parsed_at":"2022-07-22T12:32:42.952Z","dependency_job_id":null,"html_url":"https://github.com/mathisloge/protocol-doc-generation","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mathisloge%2Fprotocol-doc-generation","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mathisloge%2Fprotocol-doc-generation/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mathisloge%2Fprotocol-doc-generation/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mathisloge%2Fprotocol-doc-generation/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mathisloge","download_url":"https://codeload.github.com/mathisloge/protocol-doc-generation/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248637785,"owners_count":21137538,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":["code-generation","tools"],"created_at":"2024-11-12T17:08:57.227Z","updated_at":"2025-04-12T21:58:10.661Z","avatar_url":"https://github.com/mathisloge.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"# protodoc\n\nGenerates protocol descriptions from https://github.com/commschamp/CommsDSL-Specification schema definition files.\n\n## Usage\n\nCreate a [protodoc.json](#protodocjson) file and call `protodoc -s \"\u003cpathto\u003e/protodoc.json\"`.\n\n## CMake integration\n\nThe projects exports cmake targets.\n```cmake\nfind_package(protodoc CONFIG REQUIRED)\nprotodoc_generate(\"${CMAKE_CURRENT_SOURCE_DIR}/protodoc.json\" \"generate_doc\")\n```\n\nthe `protodoc_generate` will take two arguments. The first one is the path to the [protodoc.json](#protodocjson) and the second one is the target name.\n\nIf you use `protodoc_generate` you can use cmake variables in the [protodoc.json](#protodocjson). If you are using relative paths, please make sure that you will set `root` to the appropiate path since `protodoc_generate` will move the [protodoc.json](#protodocjson) to `${CMAKE_CURRENT_BINARY_DIR}`. So if you don't set `root`, relative paths will resolve to `${CMAKE_CURRENT_BINARY_DIR}/\u003crelative_path\u003e`.\n\nA cmake integration example can be found at [mathisloge/protodoc-cmake-example](https://github.com/mathisloge/protodoc-cmake-example).\n\n\n## protodoc.json\n\nA schema file is available at https://github.com/mathisloge/protocol-doc-generation/blob/master/schemas/protodoc.schema.json.\n\n```json\n{\n    \"root\": \"D:/dev/protodoc_configs\",\n    \"templates\": {\n        \"root\": \"\",\n        \"platforms\": \"platforms.adoc\",\n        \"namespaces\": \"namespaces.adoc\",\n        \"namespace\": \"namespaces.adoc\"\n    },\n    \"lang\": \"lang_en.json\",\n    \"custom\": \"custom.json\",\n    \"output\": \"D:/dev/commsdsl_text/asciidoc/gen\",\n    \"trim\": true,\n    \"split\": true,\n    \"jsonOutput\": true,\n    \"files\": [\n        \"protos/myschema1.xml\",\n        \"protos/myschema2.xml\",\n        \"protos/myschema3.xml\",\n        \"protos/myschema4.xml\"\n    ],\n    \"inputDir\": \"D:/dev/myschema/protos/\",\n    \"responseFile\": {\n        \"file\": \"myschema.txt\",\n        \"path\": \"D:/dev/myschema/protos/\"\n    }\n}\n```\n\nIf a file path is relativ, the path will resolve to `\u003clocation of protodoc.json\u003e/\u003cfilepath\u003e` or if `root` is specified, `\u003croot\u003e/\u003cfilepath\u003e`\n\nNote that only one of `files`, `inputDir` or `responseFile` can be present at a time.\nI don't recommend the usage of `inputDir` since it will just read the files in the order of the filesystem. In most cases the commsdsl parser would fail because of missing defines.\n\n\n| Json Field          | Description   | Required   |\n| ------------------- | ------------- |----|\n| root | prefix path for relativ dirs. if not present, the `\u003clocation of protodoc.json\u003e` will be used to resolve relative paths. | optional |\n| templates           | ||\n| templates/root      | the templates root dir.       |required|\n| templates/platforms | name of the platforms template file with the correct extension      |required|\n| templates/namespaces| name of the namespaces template file with the correct extension      |required|\n| templates/namespace | name of the namespace template file with the correct extension      |required|\n| lang                | File path to the language file. See [Language Json](#language-json)      |required|\n| custom              | file path to the merge json file. See [Custom Json](#custom-json)      |optional|\n| output              | output directory      |required|\n| trim                | remove new line after a command |optional (default: false)|\n| split               | remove whitespaces and tabs from the beginning to the start of a block |optional (default: false)|\n| jsonOutput          | dump the generated json into a file `\u003coutput\u003e/protodoc_internal.json`       |optional (default: false)|\n| files               | A array of schema files.      | required (only on of `files`, `inputDir` or `responseFile`) |\n| inputDir            | The directory containing the schema files     | required (only on of `files`, `inputDir` or `responseFile`) |\n| responseFile        | A schemas_list.txt file as described in [commsdsl-wiki#selecting-schema-files](https://github.com/commschamp/commsdsl/blob/master/doc/Manual_commsdsl2comms.md#selecting-schema-files)     | required (only on of `files`, `inputDir` or `responseFile`) |\n| responseFile/file   | the file path to the schema file      | required |\n| responseFile/path   | the file path which gets prepended to every file in the schema list file. Can be empty.      | required |\n\n\n## Language Json\nThis file contains hardcoded language strings for types and units (if used)\n\n## Custom Json\n\nThis file will get merged into the json file. If you need custom text inside of your templates, you can add this on this way. Also you could easily overwrite generated json values.\nI recommend to dump the generated json values with `jsonOutput: true` to match the correct keys you want to override.\n\n\n\n## Templates\n\nPlease see https://github.com/pantor/inja for detailed instructions of the template language.\n\nThere are some premade templates, which can be used to getting started:\n\n* https://github.com/mathisloge/protodoc-template-asciidoctor\n* https://github.com/mathisloge/protodoc-template-latex\n\n### Available Functions\n\nIn addition to the buildin inja function, the following functions are provided: \n\n| Function            | Description     | \n| ------------------- | ------------- |\n| latexText(string) | converts a string to a latex compitable string. E.g. `\\textit{my_file}` will get converted to `\\textit{my\\_file}` | \n| sortEnum(object: enumfield, string: sortfield) | will output a array with the enum field keys sorted in ascending order of `sortfield`|\n\nIf you need additional functions, please open a feature request issue.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmathisloge%2Fprotocol-doc-generation","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmathisloge%2Fprotocol-doc-generation","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmathisloge%2Fprotocol-doc-generation/lists"}