{"id":21287730,"url":"https://github.com/stjudecloud/wdldoc","last_synced_at":"2025-04-13T08:17:52.701Z","repository":{"id":37965014,"uuid":"245304377","full_name":"stjudecloud/wdldoc","owner":"stjudecloud","description":"Create WDL documentation using Markdown.","archived":false,"fork":false,"pushed_at":"2025-03-03T13:07:19.000Z","size":251,"stargazers_count":27,"open_issues_count":2,"forks_count":5,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-03-17T11:11:22.703Z","etag":null,"topics":["bioinformatics","computational-biology","cromwell","genomics","next-generation-sequencing","stjudecloud","wdl","wdl-workflow","workflow"],"latest_commit_sha":null,"homepage":"","language":"Python","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/stjudecloud.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.md","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}},"created_at":"2020-03-06T01:30:25.000Z","updated_at":"2025-01-23T15:58:25.000Z","dependencies_parsed_at":"2024-04-29T13:38:10.947Z","dependency_job_id":"a90df0f3-1fdc-4000-921f-e02129766ec7","html_url":"https://github.com/stjudecloud/wdldoc","commit_stats":{"total_commits":106,"total_committers":7,"mean_commits":"15.142857142857142","dds":0.4716981132075472,"last_synced_commit":"40fdca23b7d83e06e19d5128eef9c18a1dd3ec32"},"previous_names":[],"tags_count":21,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stjudecloud%2Fwdldoc","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stjudecloud%2Fwdldoc/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stjudecloud%2Fwdldoc/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stjudecloud%2Fwdldoc/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/stjudecloud","download_url":"https://codeload.github.com/stjudecloud/wdldoc/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245755667,"owners_count":20667027,"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":["bioinformatics","computational-biology","cromwell","genomics","next-generation-sequencing","stjudecloud","wdl","wdl-workflow","workflow"],"created_at":"2024-11-21T12:15:24.161Z","updated_at":"2025-03-27T00:08:24.376Z","avatar_url":"https://github.com/stjudecloud.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003ch1 align=\"center\"\u003e\n  wdldoc\n  \u003c/h1\u003e\n\n  \u003cp align=\"center\"\u003e\n    Convert WDL documentation to Markdown for rendering.\n    \u003cbr /\u003e\n    \u003ca href=\"https://github.com/stjudecloud/wdldoc/issues\"\u003eRequest Feature\u003c/a\u003e\n    ·\n    \u003ca href=\"https://github.com/stjudecloud/wdldoc/issues\"\u003eReport Bug\u003c/a\u003e\n    ·\n    ⭐ Consider starring the repo! ⭐\n    \u003cbr /\u003e\n  \u003c/p\u003e\n\u003c/p\u003e\n\n## Disclaimer\n\n\u003e `wdldoc` is no longer being actively developed, but we (the St. Jude Cloud team) are working on a new and improved WDL documentation generator! Star and follow [the Sprocket repo](https://github.com/stjude-rust-labs/sprocket) where we will be publishing a `sprocket doc` command!\n\n## 📚 Getting Started\n\nFor an example of what the results can look like, check out the [GitHub Pages](https://stjudecloud.github.io/workflows/) for the [St Jude Cloud Workflows](https://github.com/stjudecloud/workflows) repo! The documentation is automatically built for each release using `wdldoc`.\n\n### Installation\n\nwdldoc is only available for Python 3.8 or higher.\n\nSuggested install method:\n\n```bash\nconda create -n wdldoc python=3.8\nconda activate wdldoc\npip install wdldoc\n```\n\n## Usage\n\nwdldoc is designed to be simple, and require as little work as possible. Once installed, simply call `wdldoc .` at the root of your WDL project, and Markdown files will be generated in the `./documentation` directory for each WDL file found. There are `tasks/` and `workflows/` subdirectories, with documentation for WDL workflow files in `workflows/`, and documentation for WDL task files in `tasks/`.\n\nAny valid WDL file will have the inputs, outputs, and meta information individually documented for all its tasks and workflows. There's no need to conform to any standards we dictate; if it runs, we'll document it.\n\nAny strings found in meta fields will be treated as Markdown, so feel free to add custom bolding, italicizing, code snippets, etc.\n\nIf there's any information you want to include for a file that doesn't fit into a meta field of one of it's tasks or workflows, you can include a header section of your WDL file, and we'll convert it to Markdown and prepend it to the documentation. This is a good place to document the uses for the file and any licensing information. Simply start a line with `##` followed by a space, and the rest of the line will be parsed as Markdown. There's no limit to the number of header lines. It's good practice to break up the header into sections using Markdown titles.\n\n```text\nusage: wdldoc [-h] [-o OUTPUT_DIRECTORY] [-d DESCRIPTION] [-c CHOICES] [-v] [--debug] sources [sources ...]\n\nGenerate clean WDL documentation from source.\n\npositional arguments:\n  sources               Top level directories to search for WDL files, or the WDL files themselves.\n\noptional arguments:\n  -h, --help            show this help message and exit\n  -o OUTPUT_DIRECTORY, --output_directory OUTPUT_DIRECTORY\n                        Directory to store markdown files. Default is `./documentation`\n  -d DESCRIPTION, --description DESCRIPTION\n                        If parameter meta fields use a JSON object, the key for the field containing the input description. Default is 'help'. Ignored if only strings are used.\n  -c CHOICES, --choices CHOICES\n                        If parameter meta fields use a JSON object, the key for the field containing the input choices. Default is 'choices'. Ignored if only strings are used.\n  -v, --verbose         Sets the log level to INFO.\n  --debug               Sets the log level to DEBUG.\n```\n\nEither directories or individual files can be supplied. When directories are supplied,\nwdldoc will recursively search the input directories searching for all `.wdl` files, and generate documentation for them.\n\nWDL `parameter_meta` info can be anything that conforms to the WDL spec, but we recommend one of two formats. The first is simply `input_name: \"descriptive string\"`. The other is a JSON object containing a description key with a string value and optionally a choices key with a list of options. The value of the \"description\" and \"choices\" keys can be specified with the `--description` and `--choices` arguments. Below is an example of both formats in one parameter meta block.\n\n```text\nparameter_meta {\n    in_bams: {\n        help: \"Provide bams to run for comparison\"\n    }\n    tissue_type: {\n        help: \"Provide the tissue type to compare against\",\n        choices: ['blood', 'brain', 'solid']\n    }\n    output_filename: \"Name for the output HTML t-SNE plot\"\n}\n```\n\n## 🖥️ Development\n\nIf you are interested in contributing to the code, please first review\nour [CONTRIBUTING.md][contributing-md] document. To bootstrap a\ndevelopment environment, please use the following commands.\n\n```bash\n# Clone the repository\ngit clone git@github.com:stjudecloud/wdldoc.git\ncd wdldoc\n\n# Install the project using poetry\npoetry install\n\n# Ensure pre-commit is installed to automatically format\n# code using `black`.\nbrew install pre-commit\npre-commit install\npre-commit install --hook-type commit-msg\n```\n\n## 📝 License\n\nCopyright © 2020 [St. Jude Cloud Team](https://github.com/stjudecloud).\n\nThis project is [MIT][license-md] licensed.\n\n[contributing-md]: https://github.com/stjudecloud/wdldoc/blob/master/CONTRIBUTING.md\n[license-md]: https://github.com/stjudecloud/wdldoc/blob/master/LICENSE.md\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstjudecloud%2Fwdldoc","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fstjudecloud%2Fwdldoc","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstjudecloud%2Fwdldoc/lists"}