{"id":16824605,"url":"https://github.com/davidchambers/transcribe","last_synced_at":"2025-03-17T04:31:17.426Z","repository":{"id":30976382,"uuid":"34534630","full_name":"davidchambers/transcribe","owner":"davidchambers","description":":pencil: Generate Markdown documentation from code comments","archived":false,"fork":false,"pushed_at":"2024-01-03T09:44:30.000Z","size":72,"stargazers_count":79,"open_issues_count":2,"forks_count":6,"subscribers_count":48,"default_branch":"main","last_synced_at":"2025-03-13T17:18:48.071Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"JavaScript","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/davidchambers.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2015-04-24T18:23:02.000Z","updated_at":"2023-03-17T14:36:28.000Z","dependencies_parsed_at":"2024-06-18T21:22:34.034Z","dependency_job_id":"1cb91181-2bc1-435c-9bb0-4d44d0cf3f0a","html_url":"https://github.com/davidchambers/transcribe","commit_stats":null,"previous_names":["plaid/transcribe"],"tags_count":9,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/davidchambers%2Ftranscribe","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/davidchambers%2Ftranscribe/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/davidchambers%2Ftranscribe/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/davidchambers%2Ftranscribe/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/davidchambers","download_url":"https://codeload.github.com/davidchambers/transcribe/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243841210,"owners_count":20356443,"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":[],"created_at":"2024-10-13T11:11:28.856Z","updated_at":"2025-03-17T04:31:17.061Z","avatar_url":"https://github.com/davidchambers.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Transcribe\n\nTranscribe is a simple program which generates Markdown documentation from code\ncomments.\n\nThe general idea is that each \"export\" should be accompanied by a \"docstring\".\nThe first line of the \"docstring\" should be a Haskell-inspired type signature\nin the form `\u003cheading-prefix\u003e \u003cname\u003e :: \u003ctype\u003e`.\n\n```javascript\n//# map :: (a -\u003e b) -\u003e Array a -\u003e Array b\n//.\n//. Transforms a list of elements of type `a` into a list of elements\n//. of type `b` using the provided function of type `a -\u003e b`.\n//.\n//. ```javascript\n//. \u003e map (String) ([1, 2, 3, 4, 5])\n//. ['1', '2', '3', '4', '5']\n//. ```\nconst map = f =\u003e xs =\u003e {\n  const output = [];\n  for (let idx = 0; idx \u003c xs.length; idx += 1) {\n    output.push (f (xs[idx]));\n  }\n  return output;\n};\n```\n\nThe __`--heading-prefix`__ option specifies which lines in the source files\ncontain type signatures to become headings in the output. The default value\nis `//#`; specify a different value if using a different comment style. For\nexample:\n\n    --heading-prefix '#%'\n\nThe __`--prefix`__ option specifies which lines in the source files should\nappear in the output along with the lines prefixed with `\u003cheading-prefix\u003e`.\nThe default value is `//.`; specify a different value if using a different\ncomment style. For example:\n\n    --prefix '#.'\n\nEach line beginning with zero or more whitespace characters followed by the\nprefix is included in the output, sans prefix and leading whitespace. The `.`\nin the default prefix makes it possible to be selective about which comments\nare included in the output: comments such as `// Should never get here!` will\nbe ignored.\n\nThe __`--url`__ option specifies a template for generating links to specific\nlines of source code on GitHub or another code-hosting site. The value should\ninclude `{filename}` and `{line}` placeholders to be replaced with the filename\nand line number of each of the signature lines. For example:\n\n    --url 'https://github.com/plaid/sanctuary/blob/v0.4.0/{filename}#L{line}'\n\nAvoid pointing to a moving target: include a tag name or commit hash rather\nthan a branch name such as `main`.\n\nThe __`--heading-level`__ option specifies the heading level, an integer in\nrange \\[1, 6\\]. The default value is `3`, which corresponds to an `\u003ch3\u003e`\nelement in HTML. Specify a different value if desired. For example:\n\n    --heading-level 4\n\nThe __`--insert-into`__ option specifies the name of a file into which\nTranscribe will insert the generated output. By default, Transcribe writes to\nstdout. However, if `--insert-into` is provided, Transcribe will insert the\noutput in the specified file between two special tags: `\u003c!--transcribe--\u003e` and\n`\u003c!--/transcribe--\u003e`. For example:\n\n    --insert-into README.md\n\nThe options should be followed by one or more filenames. The filenames may\nbe separated from the options by `--`. Files are processed in the order in\nwhich they are specified.\n\nHere's a complete example:\n\n    $ transcribe \\\n    \u003e   --url 'https://github.com/plaid/example/blob/v1.2.3/{filename}#L{line}' \\\n    \u003e   -- examples/fp.js\n    ### \u003ca name=\"map\" href=\"https://github.com/plaid/example/blob/v1.2.3/examples/fp.js#L3\"\u003e`map :: (a -\u003e b) -\u003e Array a -\u003e Array b`\u003c/a\u003e\n\n    Transforms a list of elements of type `a` into a list of elements\n    of type `b` using the provided function of type `a -\u003e b`.\n\n    ```javascript\n    \u003e map (String) ([1, 2, 3, 4, 5])\n    ['1', '2', '3', '4', '5']\n    ```\n\n    ### \u003ca name=\"filter\" href=\"https://github.com/plaid/example/blob/v1.2.3/examples/fp.js#L21\"\u003e`filter :: (a -\u003e Boolean) -\u003e Array a -\u003e Array a`\u003c/a\u003e\n\n    Returns the list of elements which satisfy the provided predicate.\n\n    ```javascript\n    \u003e filter (n =\u003e n % 2 === 0) ([1, 2, 3, 4, 5])\n    [2, 4]\n    ```\n\nBy default, the output is written to stdout. One could redirect it to a file to\ngenerate lightweight API documentation:\n\n    $ printf '\\n## API\\n\\n' \u003e\u003eREADME.md\n    $ transcribe \\\n    \u003e   --url 'https://github.com/plaid/example/blob/v1.2.3/{filename}#L{line}' \\\n    \u003e   -- examples/fp.js \u003e\u003eREADME.md\n\nReading from stdin is not currently supported.\n\nOne could also insert the output into an existing file by providing the\n`--insert-into` option:\n\n    $ transcribe \\\n    \u003e   --url 'https://github.com/plaid/example/blob/v1.2.3/{filename}#L{line}' \\\n    \u003e   --insert-into README.md\n    \u003e   -- examples/fp.js\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdavidchambers%2Ftranscribe","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdavidchambers%2Ftranscribe","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdavidchambers%2Ftranscribe/lists"}